dashboard-ui

name

dashboard-ui

description

Design conventions and component vocabulary for building or revamping any dashboard UI in the BillingOS web app (apps/web). Use this WHENEVER the work touches a dashboard page, form, settings panel, table, card layout, tabs, or any merchant-facing screen under /dashboard — including new pages, redesigns, "make this look better / less cluttered", or "this form looks weird". Covers which repo components to reach for (PillTabs, CardFlat, the shared Input), elevation/border rules, progressive disclosure, empty states, and the popover/modal/toast decision. Reach for it even when the user doesn't say "design" — if you're about to add or restyle dashboard UI, read this first so the result matches the rest of the app instead of drifting.

Dashboard UI

How dashboard screens in apps/web are meant to look and behave. The goal is an orchestration of data — primary task forward, everything else deferred — not a pile of bordered boxes. When you add or revamp a dashboard surface, follow these so it matches the existing app instead of becoming a one-off.

Two hard repo rules that override taste:

• Never hand-roll primitives. Add shadcn components via the CLI: pnpm dlx shadcn@latest add <name>. (See [[feedback_shadcn_ui]] in memory.)
• Match the surrounding code — its component choices, spacing scale, and comment density. The churn section (churn/ChurnSection.tsx, churn/ChurnBuilderPage.tsx) is the current reference implementation of everything below; read it when in doubt.

Component vocabulary — reach for these first

Use the repo's existing component for the job before inventing markup. The common mistakes are using a heavier primitive than needed, or a generic one where a purpose-built one exists.

Need	Use	Not
Tabs / view-switch in a page	PillTabs / PillTabsList / PillTabsTrigger from @/components/atoms/PillTabs (pair with TabsContent from @/components/ui/tabs for panels)	raw shadcn Tabs — its TabsList is the unstyled default and won't match settings/products
Pick-one selector (offer type, mode)	PillTabs (segmented look, animated active state)	N <Button>s toggling variant="default"/"outline" — reads as amateur and the active state is invisible on dark
Stacked / nested panels inside a page	CardFlat (bg-card, no border, no shadow)	Card — its border + shadow stack into visible nested strokes
Standalone hero card on a plain bg	Card (border earns its keep here)	—
Text / number entry	shared Input / Textarea from @/components/ui/* (transparent fill, faint hairline border)	custom input markup, or any dark "well" background
Single-task overlay	see Interaction surfaces below	a modal for everything

PillTabs requires a unique layoutId per instance (it drives the sliding indicator). When you render one per list item, key it: layoutId={offer-kind-${item.key}}.

One container cue per nesting level

The most common reason a dashboard "looks weird" is stacked borders — a card border around a row border around an input border. Each nesting level should be distinguished by exactly one cue, and prefer a background-shade change over a stroke. The "Midnight Slate" dark theme ships tokens for exactly this ladder:

Level	Cue	Dark token
Page	background only	oklch(0.125 …)
Card / panel	bg-card, no border (use CardFlat)	oklch(0.165 …)
Row inside a list	divider (divide-y) or spacing — no box	—
Recessed sub-panel (e.g. expanded config)	a faint fill, bg-muted/40	—
Input	transparent + faint hairline border, blue on focus	border white/8%

Do not wrap each repeating item (a reason, a member, a webhook) in its own border box. Separate them with divide-y divide-border/60 rows. The only "edge" the user should see going down a level is a shade change, not a new line.

Inputs specifically: transparent fill, a faint border (fainter than the old oklch(0.32) stroke), blue border + ring on focus. Avoid darker-than-card "wells" — on a near-black theme they read as holes. The shared Input already encodes this; just use it.

Principle 1 — let the data drive the UI

Don't force data into generic containers. The shape of the data should pick the control.

• Categorical → chips/badges, not plain text. Time-ordered → a timeline, not time-sorted rows.
• Numbers right-aligned by place value with unit adornments (%, mo, $) so they're scannable and comparable. A bare number field with the unit smuggled into the label is a smell.
• Don't encode logic in labels. Months (0 = once) means the control can't express the data — replace with a real control (segmented Once / N months / Forever) or at least a clear field + short helper, not a magic value.
• Color is functional, not decorative. Reserve red/amber for urgent or destructive states so it actually directs attention; don't paint chips for decoration. Truncate long text to hold the layout.

Principle 2 — progressive disclosure

Showing every control at once signals inexperience. Spread actions across a spectrum of explicitness:

• Primary action front and center (search, the main CTA). Secondary actions deferred behind hover, a popover, or a … menu.
• Collapse repeating detail. A list of N configurable items should read as N compact summary rows (Too expensive · 20% off for 3mo) that expand on edit — not N fully-expanded forms stacked 300px tall.
• Move explanatory paragraphs into tooltips (InformationCircleIcon + Tooltip). They're a safety net for newcomers and clutter for experts; a tooltip serves both.
• Sequence onboarding — introduce features as the user reaches them (tooltips, a checklist), don't dump a giant modal on first load.

Principle 3 — the "invisible" UI

A finished screen leans on states the user doesn't see until they interact.

• Hover-reveal secondary/destructive controls. A per-row delete is a trash icon that fades in on group-hover, not a permanent "Remove" text button ×N. Reorder handles, copy-to-clipboard, and row actions follow the same rule. (Caveat: never hide the primary action behind hover, and remember hover doesn't exist on touch — hide only what's safe to discover late.)
• Tooltips for ambiguous labels/icons. If a label needs a sentence of explanation, that sentence belongs in a tooltip, not inline.

Dashboard structure

• Sidebar = the spine. Group related links; one nav entry per concept. If two entries point at the same concept (e.g. a builder + its analytics), merge them into one section with tabs rather than two sidebar items. Park rarely-used items (settings) at the bottom. Nav lives in components/Layout/DashboardSidebar.tsx.
• Dashboard-first. Land on the thing the user checks often (the data/overview), with configuration one click away — a tab or a header button, not the default view. The primary metric/status goes top and prominent.
• Tabs over sidebar clutter. Different views of the same concept belong in in-page PillTabs (Overview / Save flow), not extra sidebar entries.
• Empty & off states are part of the design. No data yet → a focused null-state with a single CTA, never an empty chart grid. A feature that's configured-but-inactive → a status pill plus a banner that makes the consequence and the fix obvious ("Your save flow is off — customers won't see it. [Turn it on]").

Interaction surfaces

Pick the lightest surface that fits the task:

• Popover — simple, non-blocking tweaks (display settings, a quick picker).
• Modal / Dialog — a complex, focused, blocking task (create a resource, destructive confirm). Don't reach for it for small things.
• Toast — confirmations and errors that shouldn't interrupt. Use the repo's useToast.

Optimistic UI makes things feel snappy for cheap, reversible toggles — update immediately, revert on error (see handleToggleEnabled in ChurnBuilderPage.tsx). Do not apply it to money-moving billing actions (creating coupons, pauses, cancellations): show real pending/confirmed state, because an instant "success" that later rolls back is dangerous messaging. This mirrors the Stripe-is-authoritative rule in .claude/rules/backend.md.

Revamp checklist / smell tests

When a screen "looks weird," scan for these — each maps to a fix above:

• Borders inside borders inside borders → collapse to one cue per level; use CardFlat + divide-y rows.
• Inputs with a dark fill or heavy outline → use the shared transparent Input.
• A row of buttons flipping default/outline for one choice → PillTabs.
• A label like 0 = indefinite → wrong control; add a real selector + adornment.
• Always-visible per-row "Remove"/"Edit" text → hover-reveal icon.
• Every item expanded at once → summary rows that expand on demand.
• Two sidebar entries for one concept → merge into a tabbed section.
• Empty charts on first visit → a null-state CTA instead.

Worked example

The churn section is the canonical application of all of the above:

• app/dashboard/[organization]/(header)/churn/ChurnSection.tsx — dashboard-first landing, PillTabs, status pill, null state, off-banner, merged nav.
• app/dashboard/[organization]/(header)/churn/ChurnBuilderPage.tsx — CardFlat panels, PillTabs offer selector, live preview.

Read those two files before starting a new dashboard surface — copying their structure is the fastest way to stay consistent.