Skip to Content
LYNKORIADocs

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/vite in the Vite apps, @tailwindcss/postcss in docs).
  • @lynkoria/brand/theme.css maps the brand tokens into Tailwind (bg-surface, text-muted, border-line, font-display, animate-rise, ease-brand, shadow-card). Tokens stay CSS variables using light-dark(), so utilities follow the active theme.
  • @lynkoria/brand/components.css stays 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.

On this page