Checklist
Do's and don'ts
The whole guide compressed into the rules that prevent the expensive mistakes.
Placement
Do
- Keep two resources: Experience Cloud CSS for the shell, OmniScript CSS for the script.
- Enter the static resource name only in
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 the OmniScript stylesheet field; it expects a resource name.
- Don't expect Head Markup CSS to reach inside OmniScripts 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 OmniScripts; 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.
The script itself
Do
- Consolidate per-step server work into one Integration Procedure; enable fire and forget where the user does not wait.
- Trim JSON with send and response transformations.
- Stay under roughly 750 elements per script and 10 levels of nested blocks; split big processes into reusable scripts.
- Prefill from context, validate at the current step, enable Save for later on long scripts.
- Name elements without spaces and keep names unique; they become your data-omni-key selectors.
Don't
- Don't rename elements after production deployment; integrations and selectors hang off those names.
- Don't assign ContextId inside the script; the platform reserves it for the record id.
- Don't use edit blocks in table mode where screen reader support matters; use FlexCards with data tables instead.
- Don't generate PDFs over 250 KB in-script; past 1 MB you risk timeouts.
- Don't pre-load data the user may never reach; fetch on demand at step boundaries.