A design system for running trips, not reading dashboards

The living reference for the GoDND operator portal. It has two parts: the guidelines and token architecture that govern every decision, and a component library showing each building block and its variants — rendered live from the same code that ships in the product.

Six non-negotiable rules

An operator opens the portal to find out what needs them — a trip awaiting approval, a guest waiting on a reply. Every rule serves that question, and each is enforced in code rather than left to discretion.

1. 01

   Status color is never hardcoded

   Every dot, badge, KPI value and notice resolves through statusForExperience() or worstStatus(). The status atoms take a Status, not a color — there is no prop a raw hex could arrive through.

2. 02

   Status colors never carry identity

   Green, amber and red say whether something needs the operator — nothing else. Experience types, regions, categories and chart series use brand, info and neutral, so a red line never reads as an alarm by accident.

3. 03

   Sort by what needs attention

   Lists lead with what is blocked: changes requested, then under review, then live. Bookings by nearest departure, enquiries by longest unanswered. Alphabetical order buries the one row that matters.

4. 04

   No icon-only control without a label

   Every icon button carries a visible label or an aria-label. The collapsed 66px nav expands on hover and on keyboard focus, so its labels are reachable without a mouse.

5. 05

   Never a blank screen, never a lost draft

   Lists load their rows on arrival, and an empty list names the next action. The experience builder saves every step as the operator types — closing the tab never costs work.

6. 06

   Every number has context

   “213 bookings” alone says little. Pair each value with its comparison: versus last month, seats left of capacity, or the group total a variable price produces.

Atomic design

The interface is composed bottom-up. Tokens feed atoms, atoms compose into molecules and organisms, and templates arrange them into the pages operators actually use.

1. 1

   Tokens

   Foundation
   Three-tier CSS custom properties mirrored by the Tailwind theme — the vocabulary every atom is built from.
   --brand · --card-border · --critical-tint · --brand-solid · radius · type scale
2. 2

   Atoms

   Indivisible
   The smallest units — one element, one job.
   StatusDot · Badge · Button · TextInput · Select · Checkbox · TokenChip · Avatar · Sparkline
3. 3

   Molecules

   Small groups
   A handful of atoms bound into a reusable unit.
   StatusBadge · KpiCard · PillTabs · Field · AffixInput · ChipSelect · Notice · SearchInput
4. 4

   Organisms

   Sections
   Standalone, composed regions of the interface.
   ExperiencesBoard · Panel · Sidebar · PageBar · RecordDrawer · WizardRail · DropdownMenu · Toast
5. 5

   Templates

   Layout
   Page skeletons — arrangement without real data.
   AppShell (nav + one floating surface card) · list + record drawer · rail + step form
6. 6

   Pages

   Instances
   Templates filled with an operator's real data.
   Experiences · Experience detail · New experience (7 steps) · Design system

Three-tier token architecture

No component ever names a raw value. Each tier references the one beneath it, so intent stays legible and a single edit ripples predictably through the whole platform.

Primitive tokens

The raw palette, named by hue and lightness, never by purpose.

Semantic tokens

What the platform actually references. Each maps to exactly one primitive.

Component tokens

Interaction states and composite decisions. The -solid steps exist for one reason: a fill that carries white text has to clear 4.5:1, which the base status hues do not.

Color

The card is white and the canvas sits a shade darker, so the single surface card reads as floating. Everything else inside it is a quieter step of the same slate.

Typography

One typeface: Roboto, for everything. Numerals take tabular figures globally, so prices, dates and counts line up in columns without a second, monospaced face.

Spacing & radius

A 14px gutter frames the app; radii step 6 → 9 → 10 → 12px from controls up to the surface card.

Elevation

Depth is carried by soft, cool-gray shadows. The higher the layer, the larger and softer the cast.

Buttons

One button family drives every action. The primary fill uses --brand-solid with the --brand-hover / --brand-active steps; everything else stays quiet on a hairline border.

Status & badges

Status indicators are the heart of the system. Every one takes a Status resolved in lib/status.ts — none of them accepts a color.

Metric cards

KpiCard is the workhorse — label, status chip, value, sparkline and a comparison caption, all colored by the resolved status. Summary pills give the count at a glance.

Tables & panels

Panel is the universal card with a header row. Tables right-align every number, lead each row with its status, and sort by what needs attention (rule 03).

Feedback & empty states

When something needs the operator, the notice says what and why as a first-class element instead of hiding it in a tooltip. Empty states always offer the next action.

Forms

Every control is native and shares one focus treatment — a --brand border and the --focus-ring glow. Controls sit quiet on --panel until touched; labels, hints and errors are wired to the control for assistive tech.

Overlays

Menus, the record drawer and tooltips sit on --raised or --card with a soft shadow. Each is built on a Radix primitive in shadcn's composition, so keyboard, focus and Escape behave correctly by default.

Navigation

The sidebar item is the atom of navigation — an always-labeled icon with a brand rail when active, and a genuinely disabled state for modules that aren't built yet.