Skip to Content
Work in the admin

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, 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). 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

OldNewNote
ScreenHeader with asidePage with a PageHeaderStatus beside the name, actions at the end
Card with iconCard or Section, no iconName and content share one edge
columns, mainColumnDetailLayoutOne thing: main cards plus a side column
A list of things beside the contentSettingsLayoutA choice on a phone
A list screen of a padded TableListPage with Tabs, ListToolbar and a DataTable
Table in a CardCard flush around a DataTableIt sizes to its rows; the first column stays on a phone
Show more under a listDataTable onEndReached
An eyebrow heading over a list or inside a cardSection, or the section's description
Quiet count in a card's headThe count in the Section or Card actions
BackBackButton with toIt names itself Back to ...

Fields and controls

OldNewNote
Labelled, Field with extrasField with hint, error, aside
Advice, NoteThe field's error or hint, else NoticeColour only for the error
Labelled settings in a CardRows of Row under a SectionThe row names its control; its error says what went wrong
ToggleBoxA Row with a Switch, or a SegmentedAsk what it chooses between
Segmented of five or more, a time zone's pickerSelect, or Combobox for hundredsA segment's tip moves into the row's description
Toggle chipsA multiple Combobox
Popover holding a SearchInput and a listCombobox, with OptionGroups for groupsA price or a count is the option's note
A stepper of - and + around an inputNumberField with steppermin and max hold it
DateTimeFieldDateField with time
fieldBox around a textarea and a buttonTextarea with lines and actions
Text beneath a typed valueThe Field's errorA control that parses its text calls useComplaint

Actions, overlays and feedback

OldNewNote
Button variants default, outlineprimary, secondary (and ghost)tone="danger" for what destroys
Button disabled while its request runsButton busy
Button disabled until a form is validThe button appears once it can be used
IconButton with a tipIconButton whose label is the tipheldBack says why it cannot be used now
Trash button on each rowThe row's menu (RowMenu), then Confirm for what cannot be undoneThe item names its reach
Confirm with label, icon, questionConfirm with trigger, title, consequence, action
Dialog with DialogHead iconDialogHead with a name and a descriptionA dialog's Close sits in its head alone
CreateDialog with every fieldDialog asking only what makes oneIts page opens for the rest
MenuChoices, MenuChoiceMenuRadioGroup, MenuRadioItem
MenuCheckItemMenuCheckboxItem
A chip that opens a menuA secondary Button with a ChevronDown opening MenuRadioItemsIts name says Label: value
toast with a description or an action for Undotoast with one sentence and undoid, seconds and persist keep one change in one toast; onExpire commits what waited for the Undo

Status and empty states

OldNewNote
Orb tones live, quiet, changed, destructive, workTone: positive, neutral, warning, negative, accentaccent waits for the editor
Badge variants changed, destructive, liveBadge with tone warning, negative, positiveGoing live is info
Note saying nothing is thereEmpty
UnavailableProblem with a Try again action
A hand-drawn bar or lineMeter, Sparkline, AreaChartOne 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 Fields, 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:

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.

On this page