Internals - the Experience Cloud specialty
How Salesforce Experience Cloud styling actually works
This is the engineering behind our Salesforce specialty. Once you understand the three moving parts (theme, load order, and token cascade), almost every styling surprise becomes predictable - and the selector and merge work that survives this surface is exactly what makes OmniStyler dependable on any site you own.
CSS load order and who wins
On a portal page, styles arrive in roughly this order, and later or more specific wins:
- SLDS base styles and the site's branding set (the colors you picked in Experience Builder's Theme panel).
- Site-level custom CSS: the Theme CSS editor or Head Markup.
- Component bundle CSS, including a component stylesheet static resource, which loads with the component wherever it renders.
- Inline styles written by component designers onto individual elements: icon fills, label colors, per-element backgrounds.
Inline styles beat every stylesheet except declarations marked !important. If a color will not change no matter what you write, inspect the element: if the value sits in a style attribute, change it in the designer or override it narrowly with !important. This is CSS precedence, not a platform bug.
The design token cascade
The design tokens field in Setup takes raw declarations, one per line, like --lwc-spacingMedium: 16px;. Three prefix families coexist in the one field, and each runtime reads only its own:
| Prefix | Read by | Example |
|---|---|---|
--lwc- | Aura Experience Cloud sites and Lightning pages (SLDS 1 design tokens, camelCased) | --lwc-colorBrand: #235789; |
--dxp-g- | LWR Experience Cloud sites (branding hooks) | --dxp-g-brand: #235789; |
--slds-g- | SLDS 2 themes, where global styling hooks replace design tokens | --slds-g-color-accent-1: #235789; |
Token name conversion for the --lwc- family: take the SLDS token, remove dashes, camelCase it, replace the dollar sign with --lwc-. So $spacing-xx-small becomes --lwc-spacingXxSmall. You can see this cascade live on real portals: active navigation links carry var(--lwc-colorTextActionLabelActive, var(--dxp-g-brand-1)), exactly this fallback chain.
There is a fourth, finer level: component styling hooks like --slds-c-icon-color-background, scoped to a single component type. Useful for surgical changes once the global hooks are in place.
Safari does not support these design tokens, per Salesforce's documentation. Always pair tokens with a component stylesheet so Safari users still get your brand.
Shadow DOM: why LWR is different
Aura sites use synthetic shadow DOM, so CSS from Head Markup or the Theme editor can reach inside components. LWR sites use native shadow DOM: site-level CSS stops at the component boundary and never reaches a component's internals. On LWR, style components through the things that travel with them (a component stylesheet and design tokens) and keep site CSS for the page shell.
Two more boundaries no CSS crosses: embedded dashboards render in an iframe (a separate document), and the Builder canvas adds its own chrome around your preview.
Selector stability: what to trust
| Trust level | Selectors | Why |
|---|---|---|
| Stable | slds-*, comm-*, dxp-*, siteforce*, forceCommunity* |
Public design system and Experience Cloud runtime contracts; stable across releases |
| Useful handles | [data-style-id], [data-test-id] |
Set from your own element names, so they change only when you rename things |
| Never use | lwc-* attributes, data-aura-rendered-by, generated ids like input4-45, forcegenerated-* tag names |
Generated per build, per render, or per card version; they will break silently |