# Move your screens to the admin's design system

What changed in @orbcommerce/ui, how an old part becomes a new one, the rules a screen of your own follows, and how to check it with the audit.

The admin draws every screen, its own and each product's, with one design system, exported by
`@orbcommerce/ui`. A screen of yours (a module as in
[Bring your own screens into the admin](/docs/admin/your-own-module), or an integrator's panel) uses the
same parts, so it looks and behaves like the rest and follows light and dark by itself.

If your screens were written against an earlier `@orbcommerce/ui`, this page is the way over.

## What changed

- **One import.** Everything comes from `@orbcommerce/ui`, never from a part's own file. The
  earlier components (`ScreenHeader`, `Labelled`, `ToggleBox`, `Table`, `Advice` and the rest) are
  gone, not wrapped: there is no compatibility layer.
- **One theme.** Load `@orbcommerce/ui/theme.css` once, where the admin loads its styles. The old
  and the new theme cannot be loaded side by side, so a project moves as a whole.
- **Screens arrange, the system draws.** A screen sets flex, grid, gap and width. Colour, border,
  radius, shadow and type size belong to the parts, so what a screen needs it asks the system for.
- **Parts say intent.** A column takes `min` and `grow`, a button says `primary`, a badge says
  its `tone`. No part takes a colour or a CSS string.

## Rules for a screen

**Classes.** In a `className` a screen may use layout (`flex`, `grid`, `gap-*`, `min-w-0`, widths,
spacing) and four more: `font-medium`, `font-mono`, `tabular-nums` and `text-ink-muted`. A class
that sets a colour, border, radius, shadow or type size (`bg-*`, `text-sm`, `border`, `rounded-*`,
`shadow-*`) means the system lacks a part. The admin's repository refuses them with the lint rule
`orbcommerce/no-visual-classes`; copy it if your project has its own lint setup.

**Words.** Every string a person reads comes from your module's words, in every language, written
with `defineWords` (see [Admin languages](/docs/admin/languages)). The parts say their few words
(Close, Undo, Not set) in the admin's language by themselves.

**One primary.** A surface has at most one primary action, and only when there is a real next
step. A button that cannot be used yet is not drawn grey: it appears once it can be used, and the
fields say what is missing. Where an action is held back for a reason, `IconButton` takes
`heldBack` and shows the reason in its tip.

**Undo, not confirm.** Removing something happens at once and a `toast` offers `undo`. Only what
cannot be undone asks, once, with `Confirm`, naming its reach: _Remove from Nordgrat Bikes_.

**Edits show first.** An edit appears at once and saves behind it. Your server still decides: when
it refuses, roll the value back and say plainly what to do next.

**Edit where it is seen.** A few values in place (`Rows`), many values of one record in a `Sheet`
opened by its row, a new thing in a `Dialog` that asks only what makes one. A `Dialog` focuses its
first field itself, so a screen sets no `autoFocus`.

**Two rounded layers, never three.** `Rows`, `FoldingRows` and `Card` are each a layer. Do not
wrap one in a `Card`. A `DataTable` in a card runs flush: `Card flush`.

**Fit the control to the value.** A choice whose options depend on other values is a `Select`,
never a `Segmented`. Several of a list is a multiple `Combobox`, not toggle chips. A three-digit
number does not get a full-width field.

A small screen in the system, with an optimistic switch whose change can be taken back:

```tsx
import { Page, PageHeader, Row, Rows, Section, Switch, toast } from "@orbcommerce/ui";
import { useState } from "react";

export function FleetSettings({ save }: { readonly save: (pickup: boolean) => Promise<boolean> }) {
  const [pickup, setPickup] = useState(true);

  async function change(next: boolean) {
    const before = pickup;
    setPickup(next);
    if (await save(next)) {
      toast("Pickup changed", { undo: () => void change(before) });
    } else {
      setPickup(before);
      toast.error("Pickup was not saved. Try again.");
    }
  }

  return (
    <Page header={<PageHeader title="Fleet settings" />}>
      <Section title="Handover">
        <Rows>
          <Row label="Pickup" description="Drivers collect parcels at the depot.">
            <Switch checked={pickup} onCheckedChange={(next) => void change(next)} />
          </Row>
        </Rows>
      </Section>
    </Page>
  );
}
```

## Old part to new part

An earlier part, and what it becomes. Where the new part has a different shape, the note says
what moves.

### Screens and layout

| Old                                             | New                                                     | Note                                                    |
| ----------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
| `ScreenHeader` with `aside`                     | `Page` with a `PageHeader`                              | Status beside the name, actions at the end              |
| `Card` with `icon`                              | `Card` or `Section`, no icon                            | Name and content share one edge                         |
| `columns`, `mainColumn`                         | `DetailLayout`                                          | One thing: main cards plus a side column                |
| A list of things beside the content             | `SettingsLayout`                                        | A choice on a phone                                     |
| A list screen of a padded `Table`               | `ListPage` with `Tabs`, `ListToolbar` and a `DataTable` |                                                         |
| `Table` in a `Card`                             | `Card flush` around a `DataTable`                       | It sizes to its rows; the first column stays on a phone |
| Show more under a list                          | `DataTable` `onEndReached`                              |                                                         |
| An eyebrow heading over a list or inside a card | `Section`, or the section's `description`               |                                                         |
| `Quiet` count in a card's head                  | The count in the `Section` or `Card` `actions`          |                                                         |
| `Back`                                          | `BackButton` with `to`                                  | It names itself _Back to ..._                           |

### Fields and controls

| Old                                               | New                                          | Note                                                        |
| ------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------- |
| `Labelled`, `Field` with `extras`                 | `Field` with `hint`, `error`, `aside`        |                                                             |
| `Advice`, `Note`                                  | The field's `error` or `hint`, else `Notice` | Colour only for the error                                   |
| `Labelled` settings in a `Card`                   | `Rows` of `Row` under a `Section`            | The row names its control; its `error` says what went wrong |
| `ToggleBox`                                       | A `Row` with a `Switch`, or a `Segmented`    | Ask what it chooses between                                 |
| `Segmented` of five or more, a time zone's picker | `Select`, or `Combobox` for hundreds         | A segment's tip moves into the row's description            |
| Toggle chips                                      | A multiple `Combobox`                        |                                                             |
| `Popover` holding a `SearchInput` and a list      | `Combobox`, with `OptionGroup`s for groups   | A price or a count is the option's `note`                   |
| A stepper of - and + around an input              | `NumberField` with `stepper`                 | `min` and `max` hold it                                     |
| `DateTimeField`                                   | `DateField` with `time`                      |                                                             |
| `fieldBox` around a textarea and a button         | `Textarea` with `lines` and `actions`        |                                                             |
| Text beneath a typed value                        | The `Field`'s `error`                        | A control that parses its text calls `useComplaint`         |

### Actions, overlays and feedback

| Old                                                | New                                                                  | Note                                                                                                    |
| -------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `Button` variants `default`, `outline`             | `primary`, `secondary` (and `ghost`)                                 | `tone="danger"` for what destroys                                                                       |
| `Button disabled` while its request runs           | `Button busy`                                                        |                                                                                                         |
| `Button disabled` until a form is valid            | The button appears once it can be used                               |                                                                                                         |
| `IconButton` with a `tip`                          | `IconButton` whose `label` is the tip                                | `heldBack` says why it cannot be used now                                                               |
| Trash button on each row                           | The row's menu (`RowMenu`), then `Confirm` for what cannot be undone | The item names its reach                                                                                |
| `Confirm` with `label`, `icon`, `question`         | `Confirm` with `trigger`, `title`, `consequence`, `action`           |                                                                                                         |
| `Dialog` with `DialogHead icon`                    | `DialogHead` with a name and a description                           | A dialog's Close sits in its head alone                                                                 |
| `CreateDialog` with every field                    | `Dialog` asking only what makes one                                  | Its page opens for the rest                                                                             |
| `MenuChoices`, `MenuChoice`                        | `MenuRadioGroup`, `MenuRadioItem`                                    |                                                                                                         |
| `MenuCheckItem`                                    | `MenuCheckboxItem`                                                   |                                                                                                         |
| A `chip` that opens a menu                         | A secondary `Button` with a `ChevronDown` opening `MenuRadioItem`s   | Its name says _Label: value_                                                                            |
| `toast` with a description or an `action` for Undo | `toast` with one sentence and `undo`                                 | `id`, `seconds` and `persist` keep one change in one toast; `onExpire` commits what waited for the Undo |

### Status and empty states

| Old                                                           | New                                                            | Note                          |
| ------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------- |
| `Orb` tones `live`, `quiet`, `changed`, `destructive`, `work` | `Tone`: `positive`, `neutral`, `warning`, `negative`, `accent` | `accent` waits for the editor |
| `Badge` variants `changed`, `destructive`, `live`             | `Badge` with `tone` `warning`, `negative`, `positive`          | Going live is `info`          |
| `Note` saying nothing is there                                | `Empty`                                                        |                               |
| `Unavailable`                                                 | `Problem` with a Try again action                              |                               |
| A hand-drawn bar or line                                      | `Meter`, `Sparkline`, `AreaChart`                              | One measure per chart         |

## What not to do

- **Swapping one for one.** `ToggleBox` becomes a `Switch` in the same bordered box, and the box
  was the problem. Ask what the person does on the screen, then pick the part for that.
- **A grey primary.** _Publish_ that is disabled says nothing. No primary until there is a step.
- **Saying it twice.** An issue as a badge in the head above its own `Notice`; a hint repeated
  under four fields of one card; a dialog's description repeated in its body.
- **Fixing the system in the screen.** A margin to dodge a clipped ring, a wrapper to force a
  width, a colour to mend contrast. These are faults of a part: report them.
- **`outline-none` on anything Tab reaches.** In Tailwind 4 it also silences
  `focus-visible:outline-*`, so the ring is gone for a person on the keyboard.
- **A truncating box around a link or control.** It cuts the ring. Let the element truncate itself.
- **Several controls in one `Row`.** Each takes the row's name, so a screen reader reads the same
  word for all of them. Use `Field`s, or a plain line.
- **`Section` as a grid cell.** It carries its own top margin, so cells stand at different
  heights. A heading and a gap do there.
- **A function that returns JSX, passed as a prop from inside a component** (`cell`, `editor`,
  `rowEnd`). The rows it feeds redraw on every render. Define it at module level and give it its
  state through props or a context.
- **Reducing a screen's job to the nearest part.** A grid edited cell by cell over a million rows
  is a `DataGrid`, not a `DataTable` with editable cells: the second would lose keyboard editing.

## Check a screen with the audit

Looking at a screen by eye misses what only measuring finds. `startAudit` from
`@orbcommerce/ui/audit` walks a screen with real Tab presses and reports its findings. Run it from
a browser test (Vitest's browser mode) that renders your screen:

```text
const audit = startAudit();
render(<FleetSettings save={async () => true} />);
expect(await audit.findings()).toEqual([]);
```

Start it before the screen opens, so it hears every console error. Run it in light and dark
(`document.documentElement.dataset.theme`) and at 1440 and 390 pixels wide. It reports:

- a Tab stop without a ring, a ring cut by a scrolling or clipping ancestor or by the window, and
  a ring covered by a sticky or fixed layer;
- a table that scrolls sideways although its columns fit, and on a phone a first column wider than
  half the table;
- every dialog and sheet the screen offers and a few of its menus and lists, opened from the
  keyboard: one that reaches past the window, the Tab stops inside it, and focus that does not
  come back to its trigger after Escape;
- every console error from the opening of the screen to the end of the walk.

A popup opened only by a row's action, or from inside another popup, is not reached: open it in
the test, then audit. Also walk the whole screen once with the keyboard alone: Tab order, arrows
in tables and menus, Escape closes and focus returns.

## Before you call a screen done

- Every action, state and word of the old screen exists in the new one, or is dropped on purpose.
- Loading keeps the final shape. An empty list offers one action. A failure offers Try again. A
  refused edit rolls back and says what to do next.
- The audit reports nothing in light and dark, at 1440 and 390 pixels.
- No class of the system's looks in a `className`, no string outside your words.