Design library

​

The seven rules

​

Capitalisation in product copy

​

Theme changes that apply without consumer code changes

​

0.58.0 — Petrol amendment

• teal.solid and teal.contrast — the primary button fill and its white-text contrast token.
• text.interactive — links and active nav items.
• *:focus-visible — the global keyboard focus ring.
• Every palette’s focusRing (teal, navy, green, orange, blue, gray) — all now point at teal.700. Red keeps its own red.500 ring.
• accentColor on html — native checkboxes, radios, and range inputs now tint with teal.700.

• illustration.accent — sunrise.500 (#FF8A5B) in light mode, sunrise.400 in dark mode. Use for illustration fills and strokes in empty states, onboarding art, and celebration moments (a submitted tender, a completed import).
• illustration.accentText — sunrise.700 (#C4501E, 4.65:1 on white) in light mode, sunrise.300 in dark mode. The one step safe for a small text label or icon glyph inside a piece of illustration.

• Page titles, card titles, navigation labels, and any component that sets fontFamily: "heading" explicitly continue to use Sora.
• Table cells, form fields, helper text, and all other body content now render in Inter.

​

Visual-token refresh (0.60.0)

​

0.60.1 dark-mode table fix

​

0.60.3 — status text contrast fix (light mode)

​

0.61.0 — sticky table headers and windowed long lists

​

0.62.0 — entryRow and columns[].span

​

0.62.1 — entry row pinning fixed

​

0.65.2 — sticky header fixes

​

0.66.0 — measured sticky headers across viewports

​

0.78.2: virtual list safety net

• Full render: a list of 200 rows or fewer (FULL_RENDER_FALLBACK_MAX_ROWS) that is not range-loaded renders every row, so there is nothing left to measure.
• Frozen measurement: a larger list, or any list using virtualData, stays windowed with measurement frozen. Measuring no longer re-renders, a row’s stored height only grows, and the estimate stays the one the list mounted with. Rows keep their real height; only the spacers can be off. InfiniteList paging is unchanged: the sentinel still loads one page at a time.

​

Primitives

​

PageHeader — rule 1

​

SectionCard

<SectionCard
  padded={false}
  stickyHeader
  header={
    <>
      <PageHeader title="Rates" actions={<Button>Add rate item</Button>} />
      <Toolbar px="18px" pb="3">{/* search and filters */}</Toolbar>
    </>
  }
>
  <DataTable rows={rows} columns={columns} getRowId={(row) => row.id} />
</SectionCard>

​

Toolbar

​

MultiSelectMenu (0.80.0)

<MultiSelectMenu
  label="Severity"
  allLabel="All severities"
  pluralLabel="severities"
  options={[{ value: "high", label: "High", count: 5 }]}
  value={severities}
  onChange={setSeverities}
/>

​

StatusBadge — rule 2

​

Custom status domains — registerStatusDomain

// src/statusDomains.ts in the remote, imported by its entry point.
import { registerStatusDomain } from "@stralos-co-nz/ui";

registerStatusDomain("party", {
  approved: { colorPalette: "green", label: "Approved" },
  pending: { colorPalette: "orange", label: "Approval pending" },
  suspended: { colorPalette: "red", label: "Suspended" },
  not_applicable: { colorPalette: "gray", label: "Not applicable" },
});

​

KindChip — rule 2

​

AttentionBadge

<AttentionBadge count={4}>to review</AttentionBadge>

​

DataTable — rules 4, 7

• isSelectable(id) — decides whether a row’s checkbox can be used. Use for cap enforcement (for example, refuse new selections once 500 items are chosen).
• disabledReason(id) — says why a refused row cannot be selected. The reason goes on the checkbox’s accessible name.

• enabled — false refuses windowing, including the automatic kind. Default true.
• rowHeight — row height in CSS pixels. Defaults to the height measured off the first body row at runtime. Every row must actually be this tall; variable-height rows cause the scrollbar to drift.
• overscan — extra rows rendered above and below the viewport. Default 6.
• viewportHeight — pass this in tests or server renders where the scroller has no measurable height.

• onResize(key, width) — called with the column key and its new width in CSS pixels. Wire this to api.setWidth from useDataTableColumns.
• minWidth — narrowest a column may be dragged. Default 64 px.
• step — how far one arrow-key press moves the edge. Default 16 px.
• isResizable(key) — which columns carry a grip. Defaults to every column.

• Inside a SectionCard scrolling region (the default from 0.69.0): the area stops being a scroll container. The header sticks to the top of the region with CSS position: sticky, including for wide tables that scroll sideways inside it. Pass stickyHeaderOffset to override the sticky top position.
• Inside a maxHeight scroller: the header sticks to the top of that scroller.
• On a scrolling page (scroll="page" or no SectionCard): the header parks under the app bar via --stralos-sticky-top. When the table fits its container width, the header is CSS sticky. When the table is wider than its container and scrolls horizontally, the header scrolls with the rows — horizontal scroll and page-level vertical sticky cannot coexist.

• cells — one ReactNode per data column, in columns order. Missing trailing entries render empty cells.
• action — the trailing cell beside the kebab column. Typically the submit button and any inline validation message.
• placement — "bottom" (default, after every data row) or "top" (before them). Use "top" for a short list where the row is always visible. Use "bottom" with pinned: true for a longer list.
• pinned — holds the entry row against the foot of the scroll area so a long list can still be added to without scrolling to the end. Requires maxHeight to establish the scrollport; without one the row sits at the end of the body as normal. Available from @stralos-co-nz/ui 0.62.1.
• label — accessible name for the row group. Defaults to "Add row".

<DataTable
  rows={substances}
  maxHeight="400px"
  entryRow={{
    cells: [<SubstanceNameInput />, <RateInput />],
    action: <Button type="submit">Add</Button>,
    pinned: true,
  }}
  …
/>

<DataTable
  rows={loaded}
  count={{ total, filtered: search !== "", noun: { one: "rate" } }}
  pagination={{ hasMore: loaded.length < total, onLoadMore: fetchNext, loading }}
  …
/>

<DataTable
  rows={loadedRows}
  columns={columns}
  getRowId={(row) => row.id}
  maxHeight="600px"
  count={{ total, filtered: search !== "", noun: { one: "item" } }}
  virtualData={{
    totalCount: total,
    getItem: (index) => loadedRows[index],
    onRangeChange: (start, end) => fetchRange(start, end),
    resetKey: `${sortKey}:${sortDir}`,
  }}
/>

• totalCount — the full count of rows in the result set. The table uses this to size the scroll area and set aria-rowcount correctly for assistive technology.
• getItem(index) — returns the loaded row at the given position, or undefined when that position has not been fetched yet. The index is the row’s position in the full result set, not in the loaded slice.
• onRangeChange(start, end) — called with an inclusive start and exclusive end (including overscan) whenever the visible range changes. Fetch the positions in that range and update rows and getItem in the same render.
• resetKey? — change this value when sorting or filtering changes. The table scrolls back to position 0 so the user sees the first results rather than a position that may no longer be meaningful.

{
  key: "rule",
  header: "Rule",
  render: (rule) => (isEditing(rule) ? <RuleEditorControls /> : <Text>{ruleSentence(rule)}</Text>),
  span: (rule) => (isEditing(rule) ? 2 : 1),
}

​

ReadOnlyDataTable

​

useDataTableColumns and DataTableColumnMenu

const { columns, choices, api } = useDataTableColumns(ALL_COLUMNS, {
  onColumnStateChange: (state) => save(state),
});
<DataTable columns={columns} columnPicker={<DataTableColumnMenu choices={choices} api={api} />} … />

• state — controlled state loaded from wherever you store it. Omit for the uncontrolled shape.
• defaultState — starting state when uncontrolled. Read once.
• onColumnStateChange(state, change) — called with the whole next state and a change descriptor (reason: "visibility" | "order" | "width" | "reset", key?). Not called when a change is refused.
• minVisibleColumns — how many columns must remain visible. Default 1.

• hidden — keys currently hidden. Everything else is shown.
• order — keys in display order. Unknown or dropped keys are ignored; new columns appear after stored ones.
• widths — per-column width in CSS pixels as set by a resize.

​

AiCellLabel — AI cell provenance

<AiCellLabel
  state={cell.editedAt ? "overridden" : "ai"}
  source="Sheet1, row 14"
  aiValue={formatMoney(cell.aiValue)}
  onRevert={cell.editedAt ? () => revert(cell) : undefined}
/>

• "ai" — the AI read the value and nobody has changed it. Renders an accent dot.
• "overridden" — the AI read the value and a person has since typed over it. Renders a muted dot. The only state where a revert offer makes sense.

​

RowMenu — rule 3

​

ListCount — rules 4, 7

​

KpiStrip and MetricTile — rule 7

<KpiStrip px="18px" pb="3.5">
  <MetricTile size="compact" label="Tender price" value={formatMoney(price)} helper="excl. GST" />
</KpiStrip>

​

SkeletonRows — rule 7

​

InfiniteList

<InfiniteList
  items={activities}
  totalCount={total}
  hasMore={activities.length < total}
  isLoadingMore={fetching}
  onLoadMore={fetchNext}
  renderItem={(activity) => <ActivityCard activity={activity} />}
  itemKey={(activity) => activity.id}
  emptyState={<EmptyState title="No activities yet" />}
/>

• hasMore: controls automatic loading and the end-of-list status. Defaults to totalCount !== undefined && items.length < totalCount.
• totalCount, filtered, and noun: when totalCount is set, a ListCount renders above the list: “Filtered to n items” while filtered is true, “Showing all n items” otherwise. Fewer loaded items than totalCount is paging, never filtering, so pass filtered explicitly when a filter is active. noun defaults to { one: "item" }.
• loadKey: a cursor or token that changes when a new batch is available. Pass it for cursor-based APIs so the sentinel can tell the difference between two fetches for the same batch position. Defaults to a key derived from the first and last item keys plus the list length.
• emptyState: rendered once the list settles at zero items. Not shown during the initial fetch.

​

ResponsiveRowList and RowCard

<ResponsiveRowList
  grid={<DataTable rows={rows} columns={columns} getRowId={(r) => r.id} />}
  cards={rows.map((row) => (
    <RowCard
      key={row.id}
      primary={row.name}
      meta={row.code}
      pairs={[
        { label: "Unit rate", value: formatMoney(row.unitRate) },
        { label: "Quantity", value: formatQuantity(row.quantity, row.unit) },
      ]}
      actions={<RowMenu items={[{ label: "Edit", onSelect: () => edit(row) }]} />}
      onClick={() => open(row)}
    />
  ))}
/>

​

VirtualTableBody

<Table.Root>
  <Table.Header>…</Table.Header>
  <VirtualTableBody columnCount={4} revealRow={shouldReveal ? { index: newRowIndex } : undefined}>
    {rows.map((row) => (
      <Table.Row key={row.id}>{/* … */}</Table.Row>
    ))}
  </VirtualTableBody>
</Table.Root>

​

UnitCombobox (0.72.0)

<UnitCombobox
  value={item.unitCode}
  options={unitOptions}
  ariaLabel="Unit"
  onValueChange={(code) => setUnit(code)}
/>

​

useProjectReadiness and ProjectPreparing (0.68.0)

import { classifyProjectReadinessError } from "@stralos-co-nz/domain";
import { ProjectPreparing, useProjectReadiness } from "@stralos-co-nz/ui";

function EstimatePage({ projectId }: { projectId: string }) {
  const { state, data, retry } = useProjectReadiness({
    projectId,
    // Must be a read (GET): called repeatedly and retried after failures.
    load: (signal) => estimateApi.getProjectEstimate(projectId, { signal }),
    classify: classifyProjectReadinessError,
  });

  return (
    <>
      {/* Keep mounted in EVERY state, ready included — it owns the live region. */}
      <ProjectPreparing state={state} feature="estimate" reference={projectId} onRetry={retry} />
      {state === "ready" && data ? <Estimate estimate={data} /> : null}
    </>
  );
}

• projectId — a change aborts the in-flight request and restarts from loading.
• load(signal) — the remote’s own fetch. Must be a GET. Honour signal — it is aborted on unmount and when projectId changes.
• intervalMs — poll interval while preparing. Defaults to 5000 ms, matching the service’s Retry-After: 5.
• slowAfterMs — elapsed wait before preparing becomes slow. Default 30000 ms.
• stallAfterMs — elapsed wait before the state becomes stalled. Default 120000 ms.
• classify(error) — maps an error load threw onto an outcome. Required from 0.73.0 (optional in 0.72.0). Pass classifyProjectReadinessError from @stralos-co-nz/domain (3.1.0 or later), or wrap it for your own error class. The project error codes (PROJECT_NOT_PROVISIONED_CODE, PROJECT_NOT_FOUND_CODE, PROJECT_ACCESS_REQUIRED_CODE) are exported from @stralos-co-nz/domain too; @stralos-co-nz/ui deprecated its own classifier in 0.72.0 and removed it in 0.73.0.

• Never two requests in flight. retry() during a check is a no-op.
• Aborts the in-flight request on unmount and on projectId change. A response from a stale project is ignored.
• Pauses while document.hidden. On becoming visible it checks once immediately.
• slow/stalled advance on time alone, so the message changes on schedule even while a slow request is still open.

import { PROJECT_NOT_PROVISIONED_CODE, classifyProjectReadinessError } from "@stralos-co-nz/domain";

useProjectReadiness({
  projectId,
  load,
  classify: (error) =>
    error instanceof EstimateApiError && error.code === PROJECT_NOT_PROVISIONED_CODE
      ? "preparing"
      : classifyProjectReadinessError(error),
});

​

EmptyState

• layout="inline" (default) — a bordered surface panel for empty tables, card grids, and drawers. Renders at the element’s natural width.
• layout="page" — centred both ways inside a 60vh minimum-height block, with a large glyph above the heading (defaults to FileQuestion). Use for a whole-page state such as a 404, a not-found route, or a zero-content page that is the screen’s only content.

​

Dialog with actions prop — rule 5

<Dialog
  open={open}
  onClose={close}
  size="md"
  title="Add rate item"
  actions={{ primary: { label: "Save item", onClick: save, loading: saving } }}
>
  <FormGrid>…</FormGrid>
</Dialog>

actions={{ primary: { label: "Send invites", form: "invite-form", loading: sending } }}
…
<form id="invite-form" onSubmit={send}>…</form>

​

ConfirmDialog — name the consequence

• subject — the named object, rendered first in semibold.
• consequence — one sentence explaining what confirming does.
• change: { label?, before, after } — a before → after line with tabular figures and an accessible “changes to” arrow.
• cascade — an array listed under “Also affected”; absent or empty renders nothing.
• reversibility: { reversible, note? } — “This cannot be undone.” or “You can undo this.”; note replaces that sentence when a more specific recovery path helps.

<ConfirmDialog
  open={deleting}
  title="Delete work item?"
  message="Delete this work item from the estimate?"
  subject="Work item · Drainage trench"
  consequence="The work item and its build-up will be permanently removed."
  cascade={["3 activities and their resource lines", "The attached calculator build-up"]}
  reversibility={{ reversible: false }}
  tone="destructive"
  confirmLabel="Delete work item"
  onConfirm={deleteWorkItem}
  onCancel={cancelDelete}
/>

​

Dialog titleEditor — a title renamed in place

<Dialog
  open
  onClose={close}
  title={calculator.name}
  titleEditor={{
    onRename: (name) => renameCalculator(calculator.id, name),
    fieldLabel: "Calculator name",
    buttonLabel: "Rename calculator",
    failureMessage: "Calculator could not be renamed.",
  }}
>

​

Dialog stacking, close behaviour, and scroll cues

• Focus landing outside. A combobox raised from its own onSelect closes its list and restores focus to its input, which is outside the confirm. Previously that focus movement was treated as an outside interaction and cancelled the confirm. From 0.61.1, only a pointer-down outside cancels the confirm. Focus leaving the overlay does not.
• A layer below closing. When the confirm is opened by a gesture that itself owns an overlay layer (such as a combobox’s dropdown), the combobox tears down its layer after raising the confirm. Previously that teardown cascaded into the confirm and dismissed it with no user gesture at all. From 0.61.1 the confirm ignores teardown events from layers below it; Escape, a backdrop pointer-down, and the host’s controlled actions remain its close routes.

​

SideSheet — one record, beside the list it came from

<SideSheet
  open={adding}
  onClose={() => setAdding(false)}
  title="Add project rate"
  size="lg"
  recordName={name || "New project rate"}
  confirmOnDirtyClose
  isDirty={dirty}
  actions={{ primary: { label: "Add rate", form: "project-rate-form" } }}
>
  <form id="project-rate-form" onSubmit={save}>
    <FormGrid>…</FormGrid>
  </form>
</SideSheet>

const sheet = useRef<SideSheetHandle>(null);

<SideSheet
  ref={sheet}
  open={taskId !== null}
  onClose={() => setTaskId(null)}
  title={task.name}
  recordName={task.name}
  confirmOnDirtyClose
  isDirty={dirty}
  headerActions={
    <Button onClick={() => sheet.current?.requestReplace(() => setTaskId(nextId))}>
      Next
    </Button>
  }
>

​

DialogActions — outside a dialog

actions={{ primary: { label: \"Save\", onClick: save }, wrap: true }}

actions={{
  primary: { label: \"Save changes\", onClick: save },
  destructive: (
    <Button variant=\"ghost\" colorPalette=\"red\" size=\"sm\" onClick={onDelete}>
      Delete assignment
    </Button>
  ),
}}

​

SideSheet

• requestClose() — closes through the dirty-close guard, as the × does. Does nothing while suppressDismiss is set.
• requestReplace(next) — runs next once the guard is satisfied, instead of closing. Use this for any hand-off that would otherwise bypass confirmOnDirtyClose by setting open={false} directly.

​

Mid-form create: steps inside a sheet

<SideSheet
  open={adding}
  onClose={close}
  title="Add project rate"
  size="lg"
  confirmOnDirtyClose
  isDirty={dirty}
  recordName={name}
  actions={{ primary: { label: "Add rate", form: "project-rate-form" } }}
  steps={
    creator === "supplier"
      ? [
          {
            title: "New supplier",
            recordName: draft.name || "New supplier",
            isDirty: draft.name !== "",
            onBack: () => setCreator(null),
            actions: {
              primary: { label: "Create supplier", form: "supplier-form", loading: saving },
            },
            children: (
              <SupplierForm
                id="supplier-form"
                value={draft}
                onChange={setDraft}
                onSave={create}
              />
            ),
          },
        ]
      : []
  }
>
  <ProjectRateForm id="project-rate-form" … />
</SideSheet>

• One overlay at any depth. The root form and each step stay mounted and hidden when not active, so uncontrolled fields and scroll position survive the detour.
• The title, accessible name, breadcrumb trail, and footer always reflect the active frame.
• headerActions and titleEditor from the root are hidden while a step is open.
• Cancel and Escape leave the step; the × and backdrop leave the sheet. DialogCancelButton inside a step backs out of the step, not the sheet.
• A dirty step always prompts before it is left, whether or not the sheet has confirmOnDirtyClose. Closing the sheet over a dirty step asks once.
• Focus moves into the step on open and returns to the control that triggered it on back. A polite live region announces the transition to assistive technology.

​

RichTextEditor and RichTextView (0.79.0)

<FormField label="Project scope" span="full">
  <RichTextEditor value={scope} onChange={setScope} placeholder="Describe the project scope…" />
</FormField>

<RichTextView value={project.scope} emptyText="No scope recorded." />

• RICH_TEXT_MAX_CHARACTERS (50,000): the text limit shared with api-global’s validator.
• richTextCharacterCount(doc): characters of text; line breaks and block boundaries are not counted.
• isRichTextEmpty(doc): true for null or a document whose text is only whitespace.
• richTextEquals(a, b): compares documents ignoring key order (a jsonb round trip reorders keys); every empty document equals null.

​

FormGrid and FormField span — rule 5

<FormGrid>
  <FormField label="Category" span="medium" required>…</FormField>
  <FormField label="Unit" span="medium" required>…</FormField>
  <FormField label="Item name" span="full" required>…</FormField>
</FormGrid>

​

LocationPicker

​

RateLocationPicker — whose price this is

<RateLocationPicker
  ariaLabel="Price location"
  organisationName={org.name}
  organisationLocations={orgLocations}
  suppliers={suppliers}
  value={selection}
  onSelect={setSelection}
  actions={isAdmin ? [
    { label: "Add location", onSelect: openLocationCreator },
    { label: "Add supplier", onSelect: openSupplierCreator },
  ] : []}
/>

type RateLocationPickerSelection = {
  scope: "organisation" | "supplier";
  supplierId: string | null; // always null under scope "organisation"
  locationId: string | null; // null means every location the owner has
};

<FormField label="Whose price is this?" span="full">
  <RateLocationPicker … />
</FormField>

​

Shared rate reference forms

type LocationEditorValues = {
  id?: string;
  /** Who owns the place: a parties.id, or null for ours. */
  partyId?: string | null;
  name: string;
  kind: "office" | "yard" | "depot" | "branch" | "quarry" | "other";
  addressLine1: string;
  latitude: string;
  longitude: string;
  city: string;
  region: string;
  status?: "active" | "inactive";
  countryCode?: string;
};

​

ColourPickerField

<FormField label="Schedule colour">
  <ColourPickerField
    value={form.colour}
    onChange={(hex) => setField("colour", hex)}
    noneLabel="None (automatic)"
  />
</FormField>

​

ColourSwatch

​

RegisterPage, RegisterNameLink, registerOpenColumn

<RegisterPage
  title="Fleet"
  count={fleet.length}
  search={{ value: q, onChange: setQ, label: "Search fleet" }}
  actions={<Button size="sm">Add vehicle</Button>}
>
  <DataTable
    columns={[nameCol, typeCol, registerOpenColumn({ onOpen: openEdit, getRowLabel: (r) => r.name })]}
    rows={fleet}
    getRowId={(r) => r.id}
    getRowLabel={(r) => r.name}
    rowActions={(r) => [{ label: "Edit", onSelect: () => openEdit(r) }]}
  />
</RegisterPage>

​

editedFieldProps — unsaved changes

<Input value={rate} onChange={edit} {...(dirty ? editedFieldProps : {})} />

​

SelectCombobox onCreate — making the record you are picking

<SelectCombobox
  ariaLabel="Supplier"
  value={sourceId}
  choices={supplierChoices}
  onCreate={(name) => void createSupplier(name).then((source) => setSourceId(source.id))}
  createLabel={(name) => `Create supplier "${name}"`}
  onSelect={(choice) => setSourceId(choice.value)}
/>

• Opt-in and inert without it. No onCreate, no row, and the control is otherwise unchanged.
• onCreate receives the trimmed query — the seed for the new record’s name. The hand-rolled alternative opens an empty field and asks the person to type it again.
• The row appears only while something is typed that is not already an exact match, so it cannot offer to duplicate the row above it.
• onSelect is never called for the create row. Creating is not choosing. Perform the write, then select the new record by setting value.

<SelectCombobox
  ariaLabel="Price source"
  value={sourceId}
  choices={sourceChoices}
  createEntries={[
    { label: "Create new supplier…", onCreate: startSupplier },
    { label: "Add our own price source…", onCreate: startInternal },
  ]}
  onSelect={(choice) => setSourceId(choice.value)}
/>

​

DateField and parseDateInput — rule 6

​

format helpers — rule 6

​

notify — outcome feedback

notify.info({
  title: "Recalculating the estimate",
  message: "The totals will update when the calculation finishes.",
});

const result = validation.validateAll();
if (!result.valid) return notifyValidationErrors(result);

​

useUndoAction and UndoActionBanner — undo instead of confirm

const { pendingAction, run, clear } = useUndoAction();

// In the row handler:
run({
  label: "Archived 3 rate sheets",
  impact: "−$1,240.00",
  onCommit: () => archiveOnServer(ids),
  onUndo: () => restoreLocally(ids),
});

// In the layout, once per view:
<UndoActionBanner action={pendingAction} />

• The change is on-screen already (the person can see what happened).
• The person does this action repeatedly.
• Reversing the write is straightforward.

• The change cascades to records another person may see during the window.
• The action cannot be reversed.
• The consequence is large enough that pausing is appropriate.

​

SubmitButton — aria-disabled, not disabled

​

CommandPalette — Cmd+K (0.60.0)

const [open, setOpen] = useState(false);
<CommandPalette
  open={open}
  onOpenChange={setOpen}
  items={[{ id: "new-project", label: "New project", group: "Create", onSelect: newProject }]}
/>;

• No Stralos vocabulary. The host passes items and owns every word. The default filter (0.60.1) needs every word of the query as a substring of the label, a string description, the group, or a keyword. It ranks results: label start, then a later label word, then the label anywhere, then description, then group or keywords. Groups are ordered by their best-ranking row. Before 0.60.1 the filter was a subsequence match that answered “rates” with “Construction Activities”. Pass filter to replace it with a scoring function or a server search.
• A match is always explained (0.60.1): matched text is wrapped in <mark>, and a row found only through an invisible keywords entry says Matches: <keyword>. A caller-supplied filter receives no marks.
• The list is a bounded scroller (0.60.1): min(400px, 60vh), scroll-edge shadows, the active option kept in view, and a footer with key hints (↑↓ / Enter / Esc) and the result count. From 0.61.1, the cap snaps down to the last whole-row boundary so no row is cut in half at the fold. A bottom fade appears over the last visible row while more rows remain below.
• The palette closes before the command runs, so a command may open a dialog of its own.
• The hotkey does not fire while focus is in a text field — Ctrl+K is delete-to-end-of-line there. Pass hotkey={false} where the host binds its own opener.

​

ResourceScheduler — maxHeight

• maxHeight="calc(100vh - 180px)" — fills the viewport under whatever chrome sits above it, keeping the grid’s own scroll and sticky header rows. Prefer this.
• maxHeight="none" — makes the grid as tall as its rows and lets the page scroll. Simpler, but header rows scroll away.

​

SelectableRow and SelectableRowList

​

SegmentedControl

<SegmentedControl
  aria-label="Win rate window"
  value={window}
  onValueChange={setWindow}
  options={[
    { value: "30d", label: "30d" },
    { value: "90d", label: "90d" },
    { value: "12m", label: "12m" },
  ]}
/>

​

CommandPalette — Cmd+K / Ctrl+K

<CommandPalette
  open={open}
  onClose={() => setOpen(false)}
  items={items}
  onSelect={(item) => item.onSelect()}
/>

​

Switch appearance

​

Disabled solid button in dark mode

​

Native checkbox accent

​

Muted and helper text

​

Exported layer utilities and chart colours

• coversDate, coveredDayCount, isoWeekday, and the type CoverageRange are on @stralos-co-nz/ui. They implement the working-days coverage rule behind SchedulerItem.workingDays. An empty workingDays covers nothing (the server’s empty_coverage); an omitted workingDays covers every day.
• labelColourFor, contrastRatio, relativeLuminance, LABEL_WHITE, LABEL_NAVY, and LABEL_BLACK are on @stralos-co-nz/ui (0.67.0). labelColourFor returns the text colour (white or navy.950, falling to pure black in the mid-luminance band) to use over a given #rrggbb bar fill. contrastRatio and relativeLuminance are the underlying WCAG 2.x calculations. The three LABEL_* constants are the candidate ink colours the picker rule chooses between. Guard a user-typed value with isHexColour before passing it to any of these helpers. A legend or chip drawn outside the board previously had to copy these from an internal module; they are now importable directly.
• REMOTE_ROOT_ATTRIBUTE and FOREIGN_LAYER_SCOPES are on the root barrel. The shell previously declared its own copies.

​

Icons

​

StralosLockup — shared app and sign-in branding

• sm (default) — 24 px tall (84 px wide). Keeps the AppFrame header at its existing height.
• md — 32 px tall, for sign-in cards.
• lg — 40 px tall, for large sign-in or onboarding surfaces.

​

AppFrame — back link, nav badges, and popover sub-groups

<AppFrame
  navigation={[
    { label: "All Projects", path: "/projects", scope: "project", icon: <ArrowLeft size={16} /> },
    ...projectEntries,
  ]}
  projectSelector={selector}
>

• headerContent — renders in place of the label text in the group heading row, for example an estimate-switcher dropdown that replaces the plain “Estimate” heading. The label remains the accessible group name. headerContent is hidden when the rail is collapsed; the label text is shown instead.
• leadingContent — renders as the first row inside the group, under the heading, before any navigation items. Use this when the heading should stay visible as a label and the control belongs beneath it (for example, a switcher dropdown sitting under an “Estimate” heading). The row is hidden when the rail is collapsed, and it appears in the mobile project menu. Omitting leadingContent leaves the group rendering its items as normal.

// headerContent: the switcher IS the heading
<AppFrame
  navigation={[{
    label: "Estimate",
    scope: "project",
    headerContent: <EstimateSwitcher />,
    items: estimateItems,
  }]}
  projectSelector={selector}
>

// leadingContent: the heading stays, the switcher is the first row
<AppFrame
  navigation={[{
    label: "Estimate",
    scope: "project",
    leadingContent: <EstimateSwitcher />,
    items: estimateItems,
  }]}
  projectSelector={selector}
>

​

Attention and selectable rows

​

Scheduler and resource picker additions

​

StralosLockup

​

Guided page tours

​

Rules that CI now enforces

​

Removing an export that a published package imports

/** @deprecated removed in 0.N+1.0; use X */
export { X as DeprecatedName } from "./X";

{
  when: "@stralos-co-nz/ui >=<removing release>",
  require: "<package> >=<first release without the import>",
}

​

Adopting a screen

1. Wrap content in SectionCard padded={false} and put a PageHeader at the top. Delete the local <Heading>.
2. Reduce header actions to one solid button; the rest go outline or ghost.
3. Replace the list with DataTable. Mark money and quantity columns numeric. Move units out of cells into headers. Pick a density: leave the default for a grid people act on, pass density="compact" for a long read-only reference list.
4. Replace every status chip with StatusBadge, and every kind or role chip with KindChip.
5. Give each dialog a size and an actions prop; put fields in FormGrid with spans.
6. Replace every <Input type="date"> with DateField, and every local date/money/unit template with the format helpers.
7. Check the diff for literal palette props and raw identifiers in visible text. There should be none.

​

Traps to avoid