@bluealba/pae-design-tokens
v0.0.0-integration-css.403
Published
Blue Alba Platform design tokens, cascade layer contract and base styles
Readme
@bluealba/pae-design-tokens
Single source of truth for the Blue Alba Platform CSS architecture: design tokens, the cascade layer contract and base styles.
Artifacts
| File | Purpose | Where it loads |
|---|---|---|
| dist/platform-tokens.css | Layer order declaration + all --platform-*/--pae-shell-* tokens (light & dark) + minimal document base | Inlined first in the document <head> by the gateway (index.hbs) |
| dist/shell-reset.css | Full preflight-style reset for the shell | Injected inside the shell shadow root only — never into the document |
Cascade layer contract
@layer pae.tokens, pae.base, pae.customization;pae.tokens— token definitions (:rootcustom properties,[data-theme='dark']overrides).pae.base— minimal document base (html/body) + defensive defaults scoped to[data-pae-ui](the markerinitializeMicroFrontend()puts on every micro-frontend root).pae.customization— tenant/customization overrides. Always wins over the layers above regardless of stylesheet load order (this is what makes customization deterministic).
What the contract guarantees
- Deterministic priority between platform layers, independent of load order.
- A micro-frontend using its own layers (e.g. Tailwind v4) declares them later in the document, so its CSS wins over platform layers inside its own tree.
- Tokens are consumed as CSS custom properties: they inherit into the shell shadow root and into every micro-frontend.
What it does NOT guarantee
- Un-layered CSS beats layered CSS at equal specificity. The shell is immune to hostile global CSS via Shadow DOM, not via layers.
- Isolation between micro-frontends in the light DOM. A micro-frontend
loading a global reset (e.g. an unscoped Tailwind preflight) can affect
sibling micro-frontends — scope your preflight to your own container
(
#pae-app:<module-name>).
Customization
Tenant customization stylesheets are wrapped in @layer pae.customization
automatically by usePlatformCustomization / useDynamicStyleSheet
(@bluealba/pae-ui-react-core). They should only re-declare custom
properties:
:root {
--platform-color-primary-red: 5;
--platform-color-primary-green: 35;
--platform-color-primary-blue: 100;
}