ORBCOMMERCE DOCUMENTATION
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, 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,Adviceand the rest) are gone, not wrapped: there is no compatibility layer. - One theme. Load
@orbcommerce/ui/theme.cssonce, 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
minandgrow, a button saysprimary, a badge says itstone. 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). 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:
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 OptionGroups 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 MenuRadioItems | 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.
ToggleBoxbecomes aSwitchin 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-noneon anything Tab reaches. In Tailwind 4 it also silencesfocus-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. UseFields, or a plain line. Sectionas 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 aDataTablewith 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:
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.
Bring your own screens into the admin
Give a partner's work an area of its own in the OrbCommerce Admin, show it beside the Order it came from, and start it from the Order list, without touching OrbCart's screens.
Sync from a PIM or ERP
A Source sends products, categories, register entries, offers and stock; each row is judged on its own.