Calm structure
for consequential work.

Promise

Dense work feels clear

Alignment, compact scales, and visible state make complex operations easy to scan without making the workspace feel compressed.

Personality

Neutral · precise · capable

Confident without being loud. Helpful without performing. Warmth appears in language and meaningful accents, not decoration.

Signature

Hairlines, rhythm, restraint

Tabular data, concentric corners, measured elevation, and one cedar accent create a recognizable system in either mode.

W1 · The primitive wins

One component per job. If it can't do the job, extend the primitive — never fork a local copy.

W2 · The scale is the law

Eight type sizes, seven spacing steps, three radii, four elevations, two role-based control heights. Off-scale values are out of character even when they look fine alone.

W3 · Aligned at rest

Ordinary action buttons are 32px, single-line fields are 36px, and mixed rows align their centers. Labels share one baseline and numbers one right edge.

W4 · Dense, calm, scannable

13–14px body, 32px buttons, 36px fields, ~40px rows — density paid for with hierarchy, never with clutter.

W5 · State over chrome

Only states that need attention may attract it: unsaved, running, failed, needs review. Everything decorative stays neutral.

W6 · Instant, keyboard-first, both modes

≤100ms acknowledgment, visible focus only on keyboard, full keyboard parity, WCAG 2.2 AA in light and dark alike.

W7 · Boring by design

The workspace should look barely different year over year. New capabilities feel like they were always here.

Type — 8 sizes · uppercase only where the eye scans columns

Control heights — 32px buttons · 36px single-line fields

Every ordinary action button uses the same 32px outer height. Single-line fields remain 36px; mixed button-field rows align their centers.

Radius 7 derived · 8 · 12 · pill

Concentric children share the parent's curve center: child radius = parent radius − the actual outer-edge inset, including the parent border.

Workbench chrome is guarded by npm run lint:admin-corner-radii; authored/public previews require an explicit reviewed exception.

Elevation

Sans + tabular-nums — quantities

Money is never mono. Abbreviate at five digits (12.4k) with the exact value on hover. Locale formatters only — no hand-built number strings.

Mono — identifiers, one step smaller

Identifiers earn copy buttons (hover the copy icon — tooltip); secrets are write-only: an eye toggle while entering, then a mask with Replace / Remove — a stored secret is never re-shown and never copied. Emails and names stay sans; ISO timestamps in logs may be mono.

Specialized fields — dates picked, times typed, no OS popovers

Tags — chip strip + one add control · 18 tones

Tones run slate → rose (18; unknown falls back to slate). Every chip has its ✕; extension-managed tags carry the ext badge and aren't hand-removable. Adding goes through the standard select — never freetext typed into the strip.

Labeled switch rows — the one composition

Icon toggles — aria-pressed tool states

Pressed = accent fill + hairline inset — a standalone segmented trigger. A working switch (0.55 opacity, wait cursor) must settle within ~1s.

Checkboxes — batched with Save · select-all indeterminate

Radio group — 2–5 choices in a form

Anatomy — every item type

Combobox — pinned search at ≥10 options

Multi-select uses checkbox items; the closed trigger summarizes ("3 selected", chips only when ≤2); selected items float to the top on reopen. Keyboard: ↓ ↑ Home End, typeahead, Enter, Esc back to the trigger.

Choice tiles — radio semantics, ring selection, no checkmark

Selected = border ring + 2px ring wash at 24% — nothing else. The applied option wears a separate "Current" badge when applying is its own step. 2–6 options; beyond that it's a tile grid in a picker dialog.

Media tiles — the table's visual twin · same ring when selected

One button per tile (accessible name = the record's name); name truncates, meta stays muted. Gallery / grid / list views toggle in the toolbar — the list view is the standard table. Picker dialogs (680px) embed this same grid.

Three widths — nothing else

Header: title lg/600 + optional description + ✕ (icon-sm ghost, disabled while an operation runs). Footer: ghost Cancel, then the verb button — destructive confirms focus Cancel. Esc cancels; backdrop-click closes only when the dialog holds no input; Enter submits single-input dialogs; type-to-confirm is reserved for the catastrophic tier. Max height min(85dvh, 44rem).

Long content — sticky header & footer, body scrolls

Side panel — list-context detail · 420 / 480 · 30% backdrop

Slides in 220ms; Esc or backdrop closes (dirty-form guard applies); the list keeps its scroll position. Panels never open panels — deeper work promotes to a page.

Empty tables — first run vs filtered result

First run spans every column and lets the table frame own the border; filtered empty keeps columns and controls, but drops the icon and create action.

Toasts — one event, one transient outcome

Bottom-right; six retained with the newest three collapsed; hover, focus, or touch intent expands the stack. Stable ids update retries. Every tone defaults to 4s; one optional verb action extends that to 8s; persistence is explicit. Focus never moves here. Extensions publish through the host SDK and never mount a toaster or ship toast CSS.

Upload — dropzone, drag state, file rows (filenames mono)

Concurrent uploads finish with one summary toast, not one per file.

Loading — route skeletons mirror layout · working buttons

Skeletons appear within a frame of navigation; content arrives with a 160ms fade and zero layout shift. Text only past 1s, naming the work.

Route-level failure — shared boundary, never a blank pane

The shared error boundary (.cedros-admin-shell__section-error) — resets on navigation. Unknown routes get a block empty + "Go to dashboard".

Capability-locked — setup notice · view-only banner

One setup notice per page, maximum. Driven by requiredPermission / requiredExtensionId / disabledReason — the same reasons the disabled nav shows.

Autosave chip — six states, one chip per save scope

Text crossfades 160ms; role="status", aria-live="polite". Failure escalates to the inline retry banner (Retry / Discard) beside the work — never only a toast; a conflict opens its review dialog. Explicit Save or autosave per page, never both.

Tooltip — inverted, 300ms hover / instant focus

Keyboard hints

Back breadcrumb — canonical parent, one level

Above the title; use a link when People has a route, a button only for ephemeral drill-in. Restore filters, page, and scroll; never pair it with a multi-item trail.

Pagination — one quiet row

Tables paginate; infinite scroll is for feeds only.

Avatars — 20 / 24 / 28 · stack −6px

Disclosure — config only, never status

Metric tiles — neutral, attention, unknown

Three tiles are the preferred overview set. 0 is data; — is unknown. Tone marks attention, not decoration. Eligible non-negative quantities count up for 500ms once; money, compliance values, reduced motion, and refreshes stay exact, and screen readers hear only the final value.

Links

Inline links are cedar, underline on hover; external links carry a 12px ↗; links inside table cells stay foreground with underline-on-hover so columns read calm.

Reorder — grip drags, keyboard moves, a 2px line marks the drop

Space/Enter picks up, ↑↓ moves, Esc cancels — announced politely ("Picked up Menu. Position 2 of 3."). Short lists may use the ↑/↓ button pair instead. Order persists automatically: "Changes save automatically."

Inbox & activity rows — unread is a dot + weight, never a tint

The quiet list for streams (form inbox, completed AI work) — hairline separators, accent hover, whole row activates, relative time with absolute on hover. Feeds are the one surface where infinite scroll is allowed; tables paginate.

The visual chooser

No pie/donut, gauge, radar, dual axis, 3D, map, heatmap, or decorative area chart in a dashboard contribution. Specialized analysis belongs on the extension page.

Configuration boundary

Every view states its window and source freshness. Range changes are immediate view state: keep the previous plot, mark it busy, and swap without replaying first-paint motion. Refresh failures retain last-good data, identify the failed refresh, and become stale only after the declared maximum age.

Line — direct label, last-dot only

Bars — one hue, muted comparison

Empty chart = flat hairline at zero + one micro-empty line — never an unlabeled sample. Specialized viz (the visitor globe) is palette-exempt, but its chrome consumes tokens like everything else.

Focus doctrine — visible when it helps

Style :focus-visible, never :focus. Clicking must not leave a ring; tabbing must always show one. Tab through this board—every control demonstrates the same quiet ring.

The floor

WCAG 2.2 AA both modes · keyboard parity (roving tabindex in tabs/menus/tables) · targets ≥24px, ≥32px in dense rows · color never the only signal · 11 locales via catalogs, RTL-ready · prefers-reduced-motion collapses every duration to 1ms and stops the shimmer and spinner — this board obeys; turn it on and reload.

Root, bridge, and injection — the whole recipe

<div class="loyalty-admin cedros-data"
     data-extension-id="cedros-loyalty">
  …your page, built from the §11 class contract…
</div>

/* consume host tokens; never re-emit them */
.loyalty-admin {
  --loyalty-accent: var(--cd-link, #2F6C7D);
}

/* self-inject once, id-guarded; ?inline must
   resolve nested @imports so every rule ships. */
import css from "./admin.css?inline";
const ID = "loyalty-admin-styles";
if (typeof document !== "undefined"
    && !document.getElementById(ID)) {
  const tag = document.createElement("style");
  tag.id = ID;
  tag.textContent = css;
  document.head.appendChild(tag);
}

An extension page renders native

Every element above is a host pattern — nothing custom but the data. Dashboard cards ship the full state matrix (loading skeleton · micro empty · error status with retry · capability-locked with reason) or they're not done.