Style Isolation

In OneCX, every application’s styles are confined to the DOM region that application renders into. This page is a technology-agnostic overview of the rules OneCX places on application styles and why they exist; it does not cover how to publish styles.css in the first place — that mechanic is owned by Assets and, per technology, by the Recommended Setup Expose Component Styles page.

Why style isolation matters

A single OneCX page can render content from many applications at once: the shell’s own interface (its header, navigation, and menus), the active microfrontend, and any number of remote components from other applications, all in the same document. If every application’s stylesheet applied globally, a rule written by one team could silently repaint another team’s UI, the shell’s navigation, or vice versa — the kind of cross-application breakage that is hard to trace back to its source.

To prevent this, OneCX confines each application’s styles to only the DOM elements that belong to that application. An application’s stylesheet renders that application correctly, and has no visible effect anywhere else on the page — including on other microfrontends, other remote components, and the shell itself.

How isolation is enforced

Style isolation is not a convention applications are trusted to follow — the platform enforces it structurally. When the shell loads an application’s styles.css, it wraps the stylesheet in a CSS scoping boundary tied to the DOM region that application’s content occupies on the page. Any selector in that stylesheet is only ever evaluated against elements inside that region; it cannot match, and therefore cannot affect, anything outside it (the shell’s own interface, another microfrontend, another remote component). If an application’s content is itself hosting a remote component from a different application, that boundary also stops at the nested content’s edge, so a parent application’s styles cannot leak down into a remote component it merely embeds.

One consequence of this is that a :root selector in styles.css does not do what it would in a standalone page. Instead of targeting the document root, it is automatically rewritten to target the boundary of the application’s own DOM region — so CSS custom properties an application defines under :root are available throughout its own content, but are not visible to, and do not override, any other application’s or the shell’s custom properties.

The styles.css contract

styles.css is the only sanctioned location for an application’s own styles. It is the single file the platform loads on the application’s behalf and confines to the application’s DOM region. How styles.css is exposed and loaded is described on Assets. Any CSS an application needs beyond its components' own scoped styles belongs in it, and nowhere else:

  • Do not rely on stylesheets injected outside of this mechanism (for example a <link> or <style> tag added directly to the document by application code) to style your application — the platform has no way to confine or clean up styles it did not load itself.

  • Do not assume rules in styles.css apply outside your application’s own DOM region. The platform actively confines them to it.

What belongs in styles.css

Rules in styles.css should only ever describe the appearance of elements that belong to your own application: your components' host elements, elements they render, and CSS custom properties your application defines for its own use. Selectors can be as broad as an element or attribute selector (for example button { …​ }) — broad selectors are safe here because the platform automatically confines them to your application’s DOM region; they simply never match anything outside it.

Anti-patterns to avoid

Because styles.css rules are confined to your application’s own DOM region, any rule written to reach outside that region has no effect — it is not a matter of style but simply does not do anything, which makes these patterns confusing to debug rather than merely discouraged:

  • Targeting document-level elements, such as body or html. These elements sit outside every application’s DOM region, so such rules never match.

  • Using the universal selector (*) deliberately to apply an application-wide reset inside your own DOM region. The selector still matches only your application’s descendants, so it can affect the whole application but cannot affect the shell or another application.

  • Targeting classes or IDs you do not own — for example a selector that happens to match a class name used by another application’s components, the shell’s own interface, or a shared library, in the hope of overriding its appearance. Even if the name matches, the rule is confined to your own DOM region and will not reach that content.

  • Relying on styles.css to theme other applications or the shell. Cross-application appearance (colors, fonts, spacing that should be consistent platform-wide) is a theming concern, expressed through shared theme variables, not through application styles reaching into content you do not own.

/* Anti-pattern: body and html are outside every application's DOM region */
body {
    background-color: #f5f5f5;
}

/* Correct: applies a reset across your application's own descendants only */
* {
    box-sizing: border-box;
}

/* Anti-pattern: has no effect even if the class name matches another
   application's markup — the rule is confined to your own DOM region */
.shared-card {
    border: none;
}

/* Correct: styles your own component's elements */
.my-app-summary-panel {
    border: 1px solid var(--primary-color);
}

  • Assets — owns the what and how of exposing styles.css so the shell can load it; this page owns the rules for what belongs inside it once exposed.

  • Theming — the mechanism for platform-wide, cross-application appearance (theme variables), as opposed to an individual application’s own styles.

  • Style scoping implementation deep dive — implementation details for the shell’s CSS scoping boundary.