Theming Reference

The host (wippy/facade) provides the theme. Both micro frontend apps and web components consume it. The variable catalog below is the shared vocabulary — delivery specifics are in Theming: Micro Frontend Apps and Theming: Web Components.

YAML always wins. CSS custom properties (*_css_variables) are compiled into effective Auto/forced mode blocks for pages and bridged generically through WippyElement shadow roots. Facade selector rules (*_custom_css) do not cascade across the shadow boundary, but the Web Host injects them into view.component shadow roots as of Web Host 1.0.43 (opt-out via the component's customCss flag). See the CSS Delivery Matrix.

Wippy does not use PrimeVue presets to author palettes. PrimeVue runs with theme: 'none'. Configure independent Wippy palette seeds (--p-primary, --p-secondary, --p-accent, --p-danger, --p-success, --p-warn, --p-info, and --p-help) through facade or page cssVariables. Let Wippy's canonical color-mix() formulas derive each 50–950 ladder. Do not use definePreset, duplicate a full primitive palette, or bridge only --p-primary.

Configuration casing identifies the layer:

Do not use customCSS when naming a facade backend parameter, and do not use custom_css in frontend JavaScript or package metadata.

Reference — CSS variables

The generated theme-config.css defines the canonical defaults and formulas. Facade and page cssVariables are compiled as a later, variable-agnostic override layer: top-level values apply in every mode, while @light and @dark replace selected values in the corresponding Auto and forced modes. Web components receive the same configured names through the WippyElement inheritance bridge before facade custom_css is injected.

Primary palette (11 vars)

Base: --p-primary (default: rgb(0, 95, 178))

Secondary palette (11 vars)

Base: --p-secondary (default: #6f7385)

Same 50–950 structure as primary, derived via color-mix on --p-secondary, but with its own percentage ladder — steps 300/400/700/800/950 use different mix percentages than primary, so do not assume primary's exact step values when overriding the secondary base.

Surface palette (13 vars)

Fixed light-to-dark scale — 0 is always lightest, 950 always darkest. The scale does NOT flip with dark mode. The light scale is the neutral Tailwind gray (no warm cast); the dark scale is a separate warm-toned ramp, so most levels differ between modes — only 0 and 50 are shared. Dark levels 600–950 carry the warmest undertones.

Danger / Warn / Success / Info / Help / Accent palettes

Each has an independent base var and an 11-step scale (50–950) derived via the canonical color-mix formulas in the generated @wippy-fe/theme token manifest. Do not assume that every family uses the primary percentage ladder.

Override a family base to retheme only that family; its 50–950 range auto-derives via color-mix. Changing --p-primary must not recolor danger, success, warn, info, help, secondary, or accent. Use @light / @dark only when a family needs different mode-specific values. Direct shade and alias overrides are supported for deliberate exceptions.

The token grammar (predictable naming)

The --p-* set follows one small, exceptionless grammar, so a human — or an AI agent generating styles — can predict a token name instead of looking it up. Two layers with a hard contract:

• Numeric scale — --p-<family>-{50..950} and --p-surface-{0..950}: canonical shade anchors. Defaults may be formulas or mode-specific values, and configured @light / @dark maps may override a base or an individual shade. Use semantic aliases for ordinary UI meaning.
• Semantic aliases — --p-<family>-color / -contrast-color / -hover-color / -active-color: the theme-switchable layer. -color always ships with its -contrast-color (the color to place on top of it) plus hover/active states, so no dark: pairing is needed.

Those four aliases exist for all eight families (primary, secondary, danger, success, warn, info, help, accent) — zero per-family exceptions. Typography follows the same shape (--p-font-<role>-<prop>, below). The generated tokens.json manifest shipped in @wippy-fe/theme (name, layer, light/dark value, flip flag) is the machine-readable ground truth an agent can load.

Semantic variables (mode-aware)

These flip with dark mode — use these for theme-dependent styling. Do not use numbered surface vars (--p-surface-N) for semantic colors.

Family aliases (all families)

The four --p-primary-* alias rows above exist identically for every family, remapped the same way per mode:

var(--p-success-color) + var(--p-success-contrast-color) is a mode-correct fill/on-color pair; --p-success-500 is the fixed anchor that never flips.

Typography tokens

--p-font-<role>-<prop> — roles heading / body / mono, props family, scale (size multiplier), line-height, letter-spacing, stretch, variation-settings. Mode-independent; defaults are visually inert. They steer rendered-content typography (markdown headings/body, code blocks), not host chrome.

Which font files load (families, weights, size-adjust, ascent/descent overrides) is declared via the facade fonts theming param and compiled to distributed CSS by the host.

Reference — Dark mode

Auto mode follows prefers-color-scheme. Forced mode uses the host-applied .w-theme-light / .w-theme-dark classes. The generated defaults and configured-variable layer support both paths. Key changes:

• --p-primary base shifts from rgb(0, 95, 178) to rgb(0, 125, 178) (brighter)
• --p-primary-color shifts from primary-500 to primary-400
• --p-content-background shifts from surface-0 to surface-900
• --p-text-color shifts from surface-700 to surface-0
• Surface levels diverge between modes — light uses neutral gray, dark uses a separate warm ramp (only 0 and 50 are shared); levels 600–950 carry the warmest undertones

Universal rule: every level of custom CSS must produce a sensible result in both light and dark modes.

.my-thing {
  background: var(--p-content-background);
  color: var(--p-text-color);
}

If the brand requires explicit light and dark palette values, define them in facade or page-level cssVariables, not in module CSS.

In backend css_variables YAML, use top-level values for all modes and @light / @dark for selected replacements:

css_variables:
  "--p-primary": "#dc2626"
  "--p-secondary": "#7c3aed"
  "--p-accent": "#0d9488"
  "--p-danger": "#be123c"
  "--p-success": "#15803d"
  "--p-warn": "#c2410c"
  "--p-info": "#0369a1"
  "--p-help": "#9333ea"
  "--p-warn-700": "#9a3412"                # deliberate direct shade
  "--p-help-active-color": "#6b21a8"       # deliberate direct alias
  "@light":
    "--p-content-background": "#fafafa"
    "--p-primary": "#ef4444"
  "@dark":
    "--p-content-background": "#1c1a19"
    "--p-primary": "#f87171"

The compiler emits effective Auto-light, Auto-dark, forced Light, and forced Dark blocks. For CSS intentionally authored for both a page root and a possible Web Fragment host, use paired anchors:

:root.w-theme-dark,
:host(.w-theme-dark) { /* forced-dark rule */ }

A component that is always a shadow-DOM web component may use :host(.w-theme-dark) alone. Do not put palette configuration in module-level :root; use facade or page cssVariables.

Reference — Tailwind severity utility classes

Provided by tailwindcss-primeui plugin (included in the shared Tailwind preset). Work with bg-, text-, border-, outline-, ring- prefixes.

Rule: always use semantic severity classes over raw Tailwind color names when the color conveys meaning. Never text-red-500 for danger, bg-green-100 for success, etc.

Semantic color utilities:

Animation utilities: .animate-fadein, .animate-fadeout, .animate-slidedown, .animate-slideup, .animate-scalein, .animate-fadeinleft, .animate-fadeinright, .animate-fadeinup, .animate-fadeindown, .animate-duration-{ms}, .animate-delay-{ms}, .animate-ease-*.

Reference — Host UI customization (--wippy-host-* + BEM classes)

Override host chrome through AppConfig.theming.host.cssVariables / customCSS. Shared brand theme belongs in AppConfig.theming.global; child-only overrides belong in AppConfig.theming.children and are projected into each child iframe as config.theming.global.

Scope host-chrome-only class overrides to .wippy-host-app. Intentionally shared facade selectors, including global .p-* PrimeVue rules, remain unscoped when they must apply to both host and child roots. Use children_custom_css for child-only selectors.

Layout & sidebar

BEM classes (scope with .wippy-host-app):

Splitter gutter

Chat messages

BEM classes (scope with .wippy-host-app):

Chat input

BEM classes (scope with .wippy-host-app):

Chat container

BEM classes (scope with .wippy-host-app):

Session selector

BEM classes (scope with .wippy-host-app):

Root

Anti-patterns (REJECT list)

These apply to both micro frontend apps and web components.

Color / semantic vars

• Hardcoded hex/rgb for semantic colors: color: #ef4444, background: rgb(34, 197, 94). Always use var(--p-danger-*) / var(--p-success-*) / var(--p-warn-*) / etc.
• Raw Tailwind color classes for semantic meaning: text-red-500, bg-green-100, border-yellow-300. Use severity classes: text-danger-500, bg-success-100, border-warn-300.
• Numbered --p-surface-N for theme-dependent semantic colors (e.g. color: var(--p-surface-700) for "muted text"). Use semantic aliases: var(--p-text-color), var(--p-text-muted-color), var(--p-content-background), var(--p-content-border-color).
• Component-level custom color palettes (--my-app-red, --feature-blue) declared without a documented design reason.
• Using severity tokens in decorative contexts (--p-danger-500 for "red chart category") — that implies meaning the element doesn't have.

Placement / scope

• :root { --p-* } overrides inside a child app's src/styles.css. Put shared values in facade css_variables, or page-specific values in frontend configOverrides.customization.cssVariables.
• Raw .p-button { … } / .p-dialog { … } selectors inside a child app's src/styles.css. Put shared PrimeVue selector overrides in facade custom_css, or page-specific overrides in frontend configOverrides.customization.customCSS.
• App-side <style> blocks defining @media (prefers-color-scheme: dark) rules that retune host vars.
• Theme-related CSS in src/styles.css — if it's a host-styled component, it belongs in the facade.

Components / API

• Reimplementing a PrimeVue component from scratch (custom Toast, Dialog, Accordion, Select). Use the PrimeVue component plus facade custom_css or page-level customCSS overrides.
• useToast() / useConfirm() from PrimeVue in micro frontend app code. Use host.toast(...) / host.confirm(...).
• Components that redeclare --p-* vars they should inherit (:host { --p-primary-500: #abc }).
• <Button icon="pi pi-plus"> — use <Icon> from @iconify/vue instead of the pi-* icon font.

Build / config

• Importing primevue/config directly to install the PrimeVue plugin. Use @wippy-fe/theme/primevue-plugin.
• Adding primeVueCssUrl to a WC's hostCssKeys when the WC doesn't render PrimeVue components.
• Setting proxy.injections.tailwindConfig: true in a Vite-built app (legacy runtime-Tailwind path).
• Hand-deciding whether @wippy-fe/theme JavaScript is external. Externalization follows the exact pinned Web Host import map; shadow-root CSS delivery follows hostCssKeys independently.

Related docs

• micro-frontend-app-theming.md — how micro frontend apps receive and configure theme injection
• web-component-theming.md — how web components receive the theme through shadow DOM
• micro-frontend-app.md — building Wippy micro frontend apps
• web-component.md — building Wippy web components
• host-less-mode.md — dev overlay and CSS injection in host-less mode
• compliance-checklist.md — full REJECT/WARN rules for theming