admin.ui

File structure

src/app/
├── layout.tsx                 ← Root: providers only (ThemeProvider, Toaster)
├── globals.css                ← Design tokens + Tailwind v4 config
│
├── (dashboard)/               ← Route group — owns the shell
│   ├── layout.tsx             ← AppSidebar + AppHeader + PageTransition
│   ├── page.tsx               ← /  (Dashboard)
│   ├── loading.tsx            ← Skeleton fallback for all dashboard routes
│   ├── error.tsx              ← Error boundary for all dashboard routes
│   ├── invoices/
│   │   ├── page.tsx           ← /invoices
│   │   ├── new/page.tsx       ← /invoices/new
│   │   └── [id]/
│   │       ├── page.tsx       ← /invoices/:id
│   │       └── edit/page.tsx  ← /invoices/:id/edit
│   ├── customers/page.tsx     ← /customers
│   ├── billing/page.tsx       ← /billing
│   ├── settings/page.tsx      ← /settings
│   └── profile/page.tsx       ← /profile
│
├── (auth)/                    ← Route group — no shell
│   ├── layout.tsx             ← Passthrough (required to prevent layout leak)
│   ├── signin/page.tsx        ← /signin
│   └── documentation/
│       ├── page.tsx           ← /documentation (this page)
│       ├── collapsible-code.tsx
│       └── docs-nav.tsx
│
├── not-found.tsx              ← 404 (custom)
└── global-error.tsx           ← Root-level error (has own html/body)

Status badge variants

All variants are pure CSS — no hardcoded hex. They respond to dark/light mode via the token system.

Searchable select built from Popover (@base-ui/react) + Command (cmdk). Width matches trigger via var(--anchor-width). Integrates with RHF via Controller. Used for: Customer select in invoice form, Timezone/Currency/Role in settings.

A dual-mode input: shows formatted $1,234.56 when blurred, switches to raw numeric string on focus for easy editing. Strips non-numeric characters on change. Uses inputMode="decimal" for mobile keyboards.

Calendar picker built on Popover + react-day-picker. Stores and emits values as YYYY-MM-DD strings using the local date constructor — avoids all UTC/timezone offset bugs that plague new Date(isoString).

Line items editor

Dynamic array managed with RHF useFieldArray. Each row has description, quantity, and unit price. The summary panel below reacts in real time — computing subtotal, applying tax rate and discount, then showing the final total. All math runs on the client with watched field values.

Collapsible sidebar (w-56 / w-16). Hidden on mobile — the header provides a slide-in drawer instead. Nav groups (Main / Finance / Settings) with labeled sections that collapse to icons-only mode. Uses style={{ zIndex: 10 }} — not Tailwind z-10 — because globals.css gives z-index: 1 to all aside elements outside any CSS layer.

Sticky top bar with three zones: mobile menu button (hamburger, sm:hidden) → breadcrumb (auto-generated from pathname) → right actions (notifications bell + user menu). Notification dropdown tracks unread count with per-item mark-as-read and mark-all-read. User menu logout button calls router.push('/signin').

Wraps every page inside <main>. Uses key={pathname} to force React to remount the div on each navigation, re-triggering the CSS entry animation. Intentionally has no h-full — that would collapse main's bottom padding on scrollable pages.

Overflow prevention checklist

z-index caveat

globals.css sets z-index: 1 on main, header, footer, section, asideoutside any CSS layer. This silently overrides Tailwind's z-N utilities on those elements. Fix: always use style={{ zIndex: N }} for sticky navs, dropdowns, and sidebars — never Tailwind z-classes on these element types.

Error layer summary