---
status: accepted
---

# Monolith CSS delivery; reject per-component CSS

Every consumer of `@brightspot/ui` renders **inside a CMS page** where the host-built Monolith (`v5.<hash>.css`) is already present, and the library's components are Light-DOM class-appliers that ship no CSS of their own. We therefore keep the **host-built Monolith as the single CSS delivery vehicle** for all consumers: a consumer "picks and chooses" purely by importing the component **JS** it needs, and the corresponding `btu-*` CSS is materialized once, centrally, in the Monolith. The work to make this correct is (1) **de-bloat** the Monolith by decoupling cross-referencing plugins (Option A) and (2) **complete** it by registering the plugins consumers use (e.g. tooltip/popover) plus a safelist for runtime-written classes.

## Considered options

- **Direction 1 — Precompiled per-component CSS (self-contained components).** The library compiles a static `.css` per component and ships it next to the JS, so consumers bundle exactly what they import. **Rejected:** every consumer is in-CMS, so the Monolith is already on the page — bundling component CSS only **duplicates** what's already served (confirmed: platform-automation ships ~0 `btu-*` CSS today and relies on the Monolith).
- **Direction 2 — Per-consumer Tailwind (JIT).** Add a Tailwind/PostCSS pipeline to `@brightspot/ui-builder` so each consumer compiles the classes it uses. **Rejected:** forces every consumer to adopt Tailwind (abandoning the deliberate vanilla-Vite simplicity), re-ships overlapping `btu-*` + utility CSS per consumer, and reintroduces cross-multiplication per-consumer.
- **Direction 3 — Keep and fix the Monolith.** **Chosen.**

## Consequences

- Components intentionally ship **no** styling; they are inert without a Monolith on the page. "Pick-and-choose" is a JS-import concern, not a CSS one.
- **Appearance theming** stays runtime-overridable via `--btu-theme-*` custom properties; **structural theming** (scales, new color families, variants) remains a compile-time concern owned centrally, not by consumers.
- A consumer that needs a class the Monolith doesn't contain (today: tooltip/popover) **cannot** fix it locally — the fix must land where the Monolith is built (host CMS config and/or the published preset). This is the root cause of the tooltip-styles-missing defect.
- If a true **standalone** (non-CMS) consumer ever appears, this decision must be revisited — Direction 1 would come back on the table for that consumer class.
