ADR 018: Tailwind CSS as the styling layer
- Status: Accepted
- Owner: Eng lead
- Date: 2026-11-13
Context
The console (apps/admin) and playground (apps/playground) carried about 1,470 lines of app-specific CSS on top of the shared @lynkoria/brand component sheet, while the docs site already used Tailwind v4 through Fumadocs. Layout and one-off styling lived far from the markup, and the three apps had no shared utility vocabulary for the brand tokens.
Decision
- Tailwind CSS v4 is the styling layer in all three web apps (
@tailwindcss/vitein the Vite apps,@tailwindcss/postcssin docs). @lynkoria/brand/theme.cssmaps the brand tokens into Tailwind (bg-surface,text-muted,border-line,font-display,animate-rise,ease-brand,shadow-card). Tokens stay CSS variables usinglight-dark(), so utilities follow the active theme.@lynkoria/brand/components.cssstays as the shared component layer (@layer components): buttons, cards, badges, form controls, tables, dialogs, menus, tooltips, toasts. These need pseudo-elements, native<dialog>transitions (@starting-style,::backdrop), attribute tooltips and form-control appearance, and are reused by two apps. Rewriting them as utility strings would duplicate them per app.- The Vite apps import only Tailwind's theme and utilities layers, not its preflight; the brand base layer remains the reset so existing element defaults do not change.
- App-specific stylesheets are removed. What remains outside Tailwind is documented in the CSS audit: third-party overrides (LiveKit components, Fumadocs internals) and keyframes.
- Classes are always written as complete literals (Tailwind scans source text), and repeated combinations become a named constant or component next to their use (
kpiClass,sideLink,panelClass).
Consequences
One utility vocabulary across apps; layout is visible in the markup; about 1,800 lines of CSS were removed (3,264 → 1,455). Contributors must keep class names literal and must not reintroduce per-app stylesheets for things utilities can express.