Checklist - the Experience Cloud specialty
Do's and don'ts
The whole Salesforce specialty compressed into the rules that prevent the expensive mistakes. Get these right on Experience Cloud and the same instincts keep your CSS clean on every other site.
Placement
Do
- Keep two resources: Experience Cloud CSS for the page shell, a component stylesheet for the Lightning component inside it.
- Enter the static resource name only in the component's stylesheet field (for OmniScripts,
Custom Lightning Stylesheet File Name): no .css, no link tag, no path. - Wrap CSS in a style tag when pasting into Head Markup; paste it bare into the Theme CSS editor.
- Use the design tokens field for brand colors first, CSS for shape and detail second.
- Keep all three token prefixes (--lwc-, --dxp-g-, --slds-g-) in the field; each runtime ignores the rest.
Don't
- Don't paste raw CSS into Head Markup without a style tag; the editor expects HTML and the CSS silently does nothing.
- Don't put a link tag or URL in a component's stylesheet field; it expects a resource name.
- Don't expect Head Markup CSS to reach inside Lightning components on LWR sites; native shadow DOM blocks it.
- Don't rely on design tokens alone; Safari does not support them, so keep the stylesheet as the fallback.
Selectors
Do
- Scope every site-level rule under one wrapper such as
.siteforceContentAreaor.comm-page. - Build on stable prefixes: slds-, omniscript-, omni-, vlocity-, cf-, comm-, dxp-.
- Target single elements through your own names:
[data-omni-key="CustomerEmail"],[data-test-id="NewQuote"]. - Win with specificity (scope plus class chain) before reaching for !important.
Don't
- Don't style body, html, or use the universal selector on a portal page.
- Don't reference generated artifacts: lwc- scoping attributes, data-aura-rendered-by, generated ids like input4-45, or forcegenerated-* tag names.
- Don't use :nth-child positional selectors inside components that re-render; conditional views shift element positions.
- Don't blanket-apply !important; reserve it for narrowly scoped overrides of designer inline styles.
Quality and safety
Do
- Keep text contrast at 4.5:1 or better; check it before shipping, not after the complaint.
- Keep visible focus states on every interactive element.
- Upload static resources with cache control Public so guest users get them.
- Test in a sandbox first: Builder preview, published page, guest user, mobile width, Safari.
- Re-test after each Salesforce release and keep your CSS in version control.
Don't
- Don't remove focus outlines or hide slds-assistive-text; both are accessibility plumbing.
- Don't restyle slds-hide, slds-show, or other state classes; runtime logic depends on them.
- Don't try to style dashboard iframes from page CSS; it is a separate document.
- Don't ship straight to production, and don't leave time tracking enabled there either.
- Don't hardcode sandbox URLs or org ids anywhere in CSS or markup.