CSS Injection

The Web Host uses a layered injection pipeline to give child iframes the same visual theme as the host itself. Because iframes do not inherit CSS from their parent document, the host re-injects each style asset explicitly into the child's srcdoc. Each layer is independently toggleable through ProxyConfig.

This page documents the injection pipeline, all available flags, and how to customize styles at the global, host-chrome, or per-page level. It is the canonical reference for the proxy.injections CSS flags and their runtime defaults — authoring docs that show recommended explicit values link back here. For the developer-facing theming guide (CSS variable tokens, Tailwind mapping, web component patterns), see Theming.

CSS Delivery Matrix

The facade exposes theming through three scopes — global (custom_css, css_variables, icon_sets), host (host_custom_css, host_css_variables, host_icon_sets), and children (children_custom_css, children_css_variables). The Web Host composes them per surface. Two rules govern everything below:

CSS custom properties (*_css_variables) inherit to a WC host and are bridged through its forced-theme inner root. WippyElement enumerates every effective configured name so local theme defaults cannot reset it. This is generic and independent of customCss.
CSS selector rules (*_custom_css) do not cascade across the shadow boundary. They apply only where they are injected: into each iframe document for view.page, and — as of Web Host 1.0.43 — into each view.component shadow root (opt-out via the component's customCss flag). Before 1.0.43, only variables reached it.

Facade knob	Delivers	Host shell doc	`view.page` iframe	`view.component` shadow root
`custom_css` (global)	selector rules	✓ injected	✓ injected¹	✓ injected (1.0.43+, opt-out)¹
`css_variables` (global)	custom properties	✓ effective mode blocks	✓ effective mode blocks	✓ inherited + bridged
`host_custom_css` (host)	selector rules	✓ injected	✗	✗
`host_css_variables` (host)	custom properties	✓ `:root`	✗	host-mounted WCs only²
`children_custom_css` (children)	selector rules	✗	✓ injected¹	✓ injected (1.0.43+, opt-out)¹
`children_css_variables` (children)	custom properties	✗	✓ `:root`	page WCs only²

¹ The Web Host composes what a child receives: both a view.page iframe and a view.component get global + children custom CSS merged into one sheet (children_custom_css appended after custom_css). The customCss flag is a gate, not a literal single-scope inject.

² A web component inherits its custom properties from the :root of wherever it is mounted: a host-chrome WC inherits global + host vars from the host document; a WC inside a view.page inherits global + children vars from that iframe. Its injected custom CSS is always the children scope (global + children). Keep shared styling in custom_css / css_variables (global) — those reach every surface regardless of mount location.

fs:// file support: the six theming knobs above accept an fs://<path> value resolved at request time from the content_fs filesystem — see Facade → Reusing facade theming on non-Web-Host pages. icon_sets / host_icon_sets and every non-theming JSON parameter are inline-only.

For more than a few overrides, keep CSS and JSON in separate files behind content_fs and reference them with fs://. This keeps theme assets reviewable and reusable. Do not substitute file://: that is a loader-time inlining mechanism, not the facade's request-time theming contract.

The Injection Pipeline

Styles are injected in this logical layering. The first four layers are plain <style>/<link> elements; the last two (customCSS and cssVariables) are not — they are placed in the iframe document's adoptedStyleSheets (see Override mechanism below), so they always win regardless of <head> source order:

Short answer for "CSS injection order" questions: the view.page iframe style pipeline is themeConfig → primevue/tailwind → iframe → markdown → customVariables → customCss in logical cascade order. Do not confuse this with configuration-precedence layers such as facade theme → page config_overrides → runtime override; those decide which values become customVariables/customCss, not where the resulting styles sit in the iframe cascade.

1. theme-config.css      — CSS custom properties (--p-primary-*, --p-surface-*, --p-secondary-*)
2. primevue.css          — PrimeVue component styles scoped via those variables
   tailwind.css          — Tailwind utility classes (same bundle as primevue.css)
3. iframe.css            — Default themed scrollbar styling (historical name; no iframe layout reset)
4. markdown.css          — .data-body rendering styles for Markdown content
5. cssVariables          — effective base + Auto/forced mode blocks from AppConfig.theming.global.cssVariables (adopted stylesheet)
6. customCSS             — Raw CSS from the child-projected AppConfig.theming.global.customCSS (adopted stylesheet)

This list shows the logical override order, not the literal <head> insertion order. In the production proxy the two adopted-stylesheet layers (cssVariables, then customCSS) are actually inserted before theme-config.css and PrimeVue, yet still override them — because adopted stylesheets cascade after all document <style>/<link> elements. See Override mechanism.

Each child iframe gets an independent copy of all styles, not inheritance through the cascade. Host and all children render with the same visual theme because they receive identical injected assets from the same source.

`ProxyConfig.injections.css` Flags

These nested flags are lower camelCase in both backend registry YAML and frontend package.json under wippy.proxy.injections.css. Facade requirement names use their documented snake_case names, while registry fields follow their individual schema. Nested proxy objects are passed through without key conversion. YAML wins per nested key. See Micro Frontend Apps (view.page) § Operator proxy override.

meta:
  type: view.page
  # ...
  proxy:
    enabled: true
    injections:
      css:
        themeConfig: true
        primevue: true
        customCss: true
      tailwindConfig: false

{
  "wippy": {
    "proxy": {
      "injections": {
        "css": {
          "themeConfig": true,
          "iframe": true,
          "primevue": true,
          "markdown": true,
          "customCss": true,
          "customVariables": true
        },
        "tailwindConfig": true,
        "resizeObserver": true,
        "preventLinkClicks": true,
        "iconifyIcons": true,
        "refreshWhenVisible": true,
        "historyPolyfill": true,
        "errorCapture": true
      }
    }
  }
}

CSS flags

Flag	Default	What it injects
`themeConfig`	`true`	`theme-config.css` — all `--p-primary-`, `--p-surface-`, `--p-secondary-*`, and PrimeVue semantic variables. Disabling this removes theme inheritance entirely.
`iframe`	`true`	`iframe.css` — default themed scrollbar styling. The name is historical and does not imply iframe layout rules. Keep enabled for every page for scrollbar consistency.
`primevue`	`true`	`primevue.css` + `tailwind.css` — PrimeVue component styles and Tailwind v3 utilities (~455 KB combined). Disable only while the entire artifact has no PrimeVue-like product UI. Framework choice alone is not an exception.
`markdown`	`true`	`markdown.css` — `.data-body` markdown rendering styles used by chat artifact display.
`customCss`	`true`	The `customCSS` string from the child-projected `AppConfig.theming.global`.
`customVariables`	`true`	The child-projected `cssVariables` map, compiled as effective base, Auto-light/dark, and forced Light/Dark blocks for every configured custom-property name.

There is no dedicated fonts flag. Google Fonts are delivered through theming.global.customCSS (an @import rule), which the iframe injects via the existing customCss flag.

Non-CSS injection flags

These flags sit alongside css in the injections block:

Flag	Default	What it does
`tailwindConfig`	`true`	Exposes `window.tailwind.config` for apps that use the CDN Tailwind runtime (`<script src="https://cdn.tailwindcss.com">`). Not needed for Vite builds that compile Tailwind at build time.
`resizeObserver`	`true`	Observe the child document body and send size updates to the host. This is a body-size relay, not a browser API polyfill.
`preventLinkClicks`	`true`	Intercept all `<a>` clicks inside the iframe and classify them through `host.classifyLink()` before navigating. Useful for pages with external Markdown content that may contain host-navigable links.
`iconifyIcons`	`true`	Inject registered Iconify icon sets so `<iconify-icon>` elements work offline.
`refreshWhenVisible`	`true`	Notify the child when a previously hidden iframe becomes visible again.
`historyPolyfill`	`true`	No-op today. The history polyfill is intentionally disabled for `srcdoc` iframes (`window.location` is non-configurable), so this flag has no runtime effect. The runtime always installs a history guard instead, which stubs `window.history` methods and warns to use memory-history routing — apps must use memory mode (e.g. `createAppRouter` memory history). Setting this flag does not make SPA route changes observable by the host.
`errorCapture`	`true`	Attach `window.onerror` and `window.onunhandledrejection` handlers that forward uncaught errors to the host via `logger.captureException`. Enable in production for centralized error collection.

If a page omits wippy.proxy.injections, the iframe proxy has permissive runtime defaults and enables most injections. Vite micro frontend apps should still declare the explicit values they rely on so a package review can see whether the app expects host CSS, link interception, body-size reporting, or error capture.

Disabling unwanted injections

A page may disable PrimeVue injection only while it contains no standard product controls or surfaces that PrimeVue provides. A canvas/SVG/chart-only page is valid. Once it gains a button, input, form, table, dialog, menu, tag, tooltip, or feedback control, use PrimeVue and keep the injection enabled; framework choice alone is not an omission reason.

{
  "wippy": {
    "proxy": {
      "injections": {
        "css": {
          "primevue": false,
          "themeConfig": false
        }
      }
    }
  }
}

With both disabled the page still receives customCSS, cssVariables, and iframe.css (scrollbar reset) unless those are also turned off. The proxy API, state relay, and WebSocket bridge are unaffected by CSS flags.

Web Components: facade custom CSS + `hostCssKeys`

Web components do not go through the iframe injection pipeline. Two channels bring the theme into a component's shadow root:

Configured variables + facade custom CSS. @wippy-fe/webcomponent-core enumerates every effective global/children/page custom-property name, including names under @light / @dark, and installs a generic inheritance bridge after platform theme defaults. It then installs composed global + children customCSS as the final layer. customCss: false disables only the selector-rule layer; it does not disable configured-variable propagation.
Platform CSS assets (hostCssKeys). theme-config.css, PrimeVue, markdown, and iframe/scrollbar styles are static bundle assets, not the facade's configured CSS. A component requests the ones it needs by URL through wippyConfig.hostCssKeys (or fetches them ad hoc with loadCss() from @wippy-fe/proxy), and the runtime injects them into the shadow root.

static get wippyConfig() {
  return {
    hostCssKeys: ['themeConfigUrl', 'primeVueCssUrl'] as const,
  }
}

Use declarative hostCssKeys for normal component authoring. loadCss() is an integration escape hatch; never rewrite a mounted shadow tree with shadowRoot.innerHTML.

Available hostCss keys:

Key	Content	Bundle impact
`hostCss.themeConfigUrl`	CSS variables (`--p-primary-*`, light + dark)	Small (~5 KB)
`hostCss.primeVueCssUrl`	PrimeVue components + Tailwind utilities	Large (~455 KB)
`hostCss.markdownCssUrl`	`.data-body` markdown rendering styles	Small
`hostCss.iframeCssUrl`	Scrollbar styling using `--p-surface-*`	Tiny
`hostCss.preflightCssUrl`	Tailwind/PrimeVue preflight base reset (normalize/reset)	Small

A web component that wants host-faithful rendering may need to fetch hostCss.preflightCssUrl explicitly via loadCss(), because the host's base preflight reset does not cross the shadow boundary.

For guidance on which keys to request and when — including the decision tree for balancing style fidelity against Shadow DOM bundle size — see WC Theming § hostCssKeys decision tree.

`AppConfig.theming` Projection

The facade config exposes three theming scopes: theming.global, theming.host, and theming.children. Before a page iframe receives its child config, the host projects the effective child theme into AppConfig.theming.global. That child global scope is what customCss and customVariables inject into the iframe.

Keys are CSS variable names exactly as they should appear in CSS:

// In the facade configuration or SetConfig PostMessage payload.
theming: {
  global: {
    cssVariables: {
      '--p-primary': 'rgb(220, 38, 38)',
      '--p-surface-0': '#0f0f0f',
      '--p-content-border-radius': '2px',
    }
  }
}

The compiler normalizes leading --, merges the top-level base with @light / @dark, and emits effective Auto-light, Auto-dark, forced Light, and forced Dark blocks in the iframe's adopted stylesheet. It is variable-agnostic: palette bases, direct shades/aliases, surfaces, typography, host tokens, and application-specific properties follow the same path. The override does not depend on <head> source order — see Override mechanism.

Override mechanism: adopted stylesheets

customCSS and cssVariables are not ordinary <head> <style>/<link> elements. The proxy places them in the iframe document's adoptedStyleSheets (constructable stylesheets). Per the CSS cascade, adopted stylesheets always order after all <style>/<link> document stylesheets regardless of insertion order, so they always win over theme-config.css, primevue.css, iframe.css, and markdown.css. In the production proxy these custom layers are in fact inserted before theme-config.css and PrimeVue; the override still holds because it comes from the adopted-stylesheet cascade position, not from <head> source order.

Between the two custom layers, customCSS overrides cssVariables: the adopted sheets are ordered cssVariables first, then customCSS, and later adopted sheets have higher priority. If the same --p-* token is set in both, the customCSS value wins.

Three theming scopes

The facade supports three cssVariables scopes to target different rendering layers:

Scope key	Injected into	Use case
`theming.global`	Host chrome and every child iframe	Brand colors, primary palette, shared icon sets
`theming.host`	Host chrome only	Sidebar, header, chat, and app-title overrides
`theming.children`	Child iframes only	Child-only CSS variables and CSS overrides

Child iframes do not receive theming.host or theming.children as separate scopes. They receive the merged child-facing result as config.theming.global.

Per-page overrides

Individual pages can override variables via window.__WIPPY_CONFIG_OVERRIDES__ (set in the page's registry entry as meta.config_overrides, or in package.json as wippy.configOverrides):

window.__WIPPY_CONFIG_OVERRIDES__ = {
  customization: {
    cssVariables: {
      '--p-primary': '#ff6b00',
    },
    customCSS: '.my-page-header { border-radius: 12px; }',
  },
}

Backend YAML config_overrides.customization is the per-page authoring surface. Its cssVariables and customCSS keys project into frontend theming.global.cssVariables and customCSS before the page receives AppConfig, replacing the inherited child values for that page. Because the override is merged into theming.global, it propagates down the whole nested sub-tree: every child the page embeds — <w-iframe>, <w-artifact>, and html.inject content — is built from the page's already-merged config and inherits the theme, recursively. So a page (or a module shipping several such pages) themes everything beneath it, not just itself.

`--wippy-host-*` Variables

The host exposes a set of --wippy-host-* CSS variables for customizing Web Host chrome elements — sidebar, chat bubbles, input bar, panel dividers — without touching child iframe styles. Override them via customCSS or cssVariables scoped to :root (the variables are already prefixed and do not leak into child iframes):

theming: {
  host: {
    customCSS: `
    :root {
      --wippy-host-sidebar-width-open: 20rem;
      --wippy-host-splitter-color: transparent;
      --wippy-host-message-radius: 0.5rem;
      --wippy-host-message-user-bg: var(--p-info-100);
      --wippy-host-message-agent-bg: var(--p-warn-100);
    }
    /* Class selectors must be scoped to .wippy-host-app */
    .wippy-host-app .chat-message__footer { display: none; }
  `
  }
}

Layout variables

Variable	Default	Description
`--wippy-host-sidebar-width-open`	`16rem`	Sidebar width when expanded
`--wippy-host-sidebar-width-closed`	`3.5rem`	Sidebar width when collapsed
`--wippy-host-splitter-width`	`1px`	Panel divider line width
`--wippy-host-splitter-hit-area`	`10px`	Panel divider drag area
`--wippy-host-splitter-color`	`surface-200/600`	Panel divider color
`--wippy-host-chat-bg`	`surface-50/700`	Chat container background
`--wippy-host-chat-padding-x`	`10px`	Message list horizontal padding
`--wippy-host-meta-bar-border-color`	`surface-200/600`	Agent/model bar border

Message variables

Variable	Default	Description
`--wippy-host-message-bg`	`surface-50/700`	Default message background
`--wippy-host-message-border-color`	`surface-200/600`	Message bubble border
`--wippy-host-message-shadow`	`0 1px 2px 0 rgba(...)`	Message bubble shadow
`--wippy-host-message-font-size`	`0.875rem`	Message body text size
`--wippy-host-message-radius`	`1rem`	Message bubble corners
`--wippy-host-message-padding-x`	`1rem`	Message horizontal padding
`--wippy-host-message-padding-y`	`0.5rem`	Message vertical padding
`--wippy-host-message-gap`	`0.5rem`	Gap between avatar and bubble
`--wippy-host-message-spacing`	`1rem`	Vertical spacing between messages
`--wippy-host-message-user-bg`	`primary-50`	User message background
`--wippy-host-message-agent-bg`	`yellow-50/surface-800`	Agent message background
`--wippy-host-tool-bg`	`help-50`	Tool call background
`--wippy-host-tool-border`	`help-300`	Tool call left border
`--wippy-host-avatar-size`	`2rem`	Message avatar diameter

Input variables

Variable	Default	Description
`--wippy-host-input-bg`	`surface-50/700`	Input bar background
`--wippy-host-input-border-color`	`surface-200/600`	Input bar top border
`--wippy-host-input-group-bg`	`surface-0/800`	Input field background
`--wippy-host-input-group-border-color`	`surface-300/700`	Input field border
`--wippy-host-input-group-radius`	`0.375rem`	Input field corners
`--wippy-host-input-min-height`	`2.5rem`	Textarea initial height
`--wippy-host-input-max-height`	`10rem`	Textarea max height

Prompt variables

Variable	Default	Description
`--wippy-host-prompt-bg`	`surface-100/800`	Prompt suggestion background
`--wippy-host-prompt-border-color`	`surface-300/600`	Prompt suggestion border
`--wippy-host-prompt-radius`	`0.5rem`	Prompt suggestion corners

These variables only affect the host chrome. Child iframe styles are unaffected — they receive only the standard injection pipeline described above.