Skip to main content

Frontend & Design System

The web frontend (Next.js) is built on TailwindCSS + shadcn/ui + Tailwind UI. This page defines what each is for, how they compose, and — crucially — how they deliver per-tenant runtime branding without code changes.

The three layers​

LayerWhat it isUsed for
TailwindCSSUtility-first CSS frameworkthe styling foundation everywhere (spacing, color, layout, responsive)
shadcn/uiAccessible components (Radix primitives + Tailwind) you copy into the repo and ownapp/dashboard UI: forms, tables, dialogs, menus, toasts, command palettes
Tailwind UIProfessionally designed Tailwind blocks/templates (Tailwind Labs, commercial)marketing/storefront/ecommerce sections: hero, product grids, pricing, checkout, navigation

Rule of thumb: Tailwind UI for marketing & storefront surfaces (conversion-oriented, content-heavy), shadcn/ui for application surfaces (dashboards, dealer/admin portals, forms). Both are pure Tailwind, so they share one token system.

Why this stack​

  • One token system — Tailwind theme tokens drive both shadcn/ui and Tailwind UI, so the whole site themes consistently.
  • Accessibility built-in — shadcn/ui sits on Radix (keyboard, focus, ARIA), helping hit the Lighthouse a11y budget.
  • You own the components — shadcn/ui is copied in, not a black-box dependency → easy to adapt, no version lock-in, no runtime bloat.
  • Speed — Tailwind UI blocks give production-grade marketing/ecommerce layouts fast (storefront, pricing, checkout) instead of hand-building.
  • Perfect for white-label — theming is just CSS variables (next section).

Per-tenant theming (the white-label payoff)​

shadcn/ui and Tailwind UI both read CSS custom properties for color/radius/spacing. We map the Tenant Config Contract branding.colorTokens onto those variables at the layout root, so the same components rebrand per tenant at runtime.

// app/layout.tsx (sketch) — tokens come from the tenant config service
const { colorTokens, fontFamily, radius } = await getTenantBranding();
const styleVars = {
['--primary']: colorTokens.primary,
['--accent']: colorTokens.accent,
['--radius']: radius ?? '0.5rem',
['--font-sans']: fontFamily ?? 'Inter',
} as React.CSSProperties;

return (
<html lang={locale}>
<body style={styleVars} className="font-sans bg-background text-foreground">
{children}
</body>
</html>
);
/* tailwind theme bound to the CSS vars — same build, any brand */
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222 47% 11%;
/* --primary / --accent / --radius injected per tenant at runtime */
}
}
  • No rebuild per brand — logo/colors/font/radius come from config; the image is identical across tenants (Multi-Tenancy).
  • Logo & imagery load from the tenant's object-storage bucket via CDN.
  • Dark mode via the same variable scheme ([data-theme='dark']).

Structure (web)​

web/
app/ # Next.js App Router (localized routes)
components/
ui/ # shadcn/ui components (owned, themable)
marketing/ # Tailwind UI–derived blocks (hero, pricing, footer…)
storefront/ # product card, configurator, cart, checkout
dashboard/ # team dashboards (shadcn tables/charts)
lib/
tenant.ts # resolve TenantConfig → theme vars
i18n.ts # next-intl setup
styles/
globals.css # tailwind base + token vars
tailwind.config.ts # tokens bound to CSS vars

Where each is applied (per surface)​

SurfaceTailwindshadcn/uiTailwind UI
Storefront (marketing, PDP, cart)✅forms/dialogs/toasts✅ hero/grids/checkout
Team dashboards (marketing/finance/service-head)✅✅ tables/charts/forms—
Dealer/admin portals✅✅occasional blocks
Auth / onboarding✅✅✅ sign-in blocks

Accessibility & performance​

  • Radix-based components → keyboard + screen-reader support out of the box.
  • Tailwind's JIT + tree-shaking → minimal CSS; no runtime CSS-in-JS cost.
  • Server-render content (no client-only theming flash): inject tenant vars server-side.
  • Meets testing budgets (a11y ≥ 95, perf ≥ 90) including across locales.

Mobile note​

React Native apps do not use Tailwind/shadcn (web DOM libs). They share the design tokens (colors/spacing/typography) via a small cross-platform token package, themed from the same Tenant Config, so web and app stay visually consistent. See Apps.

Licensing note​

  • TailwindCSS, shadcn/ui — free/open (MIT-style).
  • Tailwind UI — commercial license (per-developer/team). Budget for it; usage is copy-paste blocks, no runtime dependency.