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
| Layer | What it is | Used for |
|---|---|---|
| TailwindCSS | Utility-first CSS framework | the styling foundation everywhere (spacing, color, layout, responsive) |
| shadcn/ui | Accessible components (Radix primitives + Tailwind) you copy into the repo and own | app/dashboard UI: forms, tables, dialogs, menus, toasts, command palettes |
| Tailwind UI | Professionally 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)
| Surface | Tailwind | shadcn/ui | Tailwind 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.