Target: Spring '26, SLDS 2 GA since Winter '26. Sources: SLDS Linter developer guide, SLDS Linter repo, Enhanced Lightning Experience / SLDS 2.
1. What SLDS 2 changes
SLDS 2 is the styling system behind Enhanced Lightning Experience and the Cosmos theme. The important consequence for component code: appearance now comes from styling hooks, not from SLDS class internals. A component that reached into .slds-button__icon or replaced a base component's markup to get a look will drift, break on theme changes, and lose the user's theme entirely.
Three kinds of custom property:
| Kind | Example | Use |
|---|---|---|
| Global styling hooks | --slds-g-color-accent-container-1, --slds-g-spacing-4, --slds-g-font-scale-2 |
Your own markup, so it follows the org's theme |
| Component styling hooks | --slds-c-card-color-background, --slds-c-button-brand-color-background |
Adjusting a base component from the outside, the supported way |
Legacy --lwc-* tokens |
--lwc-brandPrimary |
Do not use in new code; they are the SLDS 1 aliases and are what the linter flags first |
2. Doing it correctly
/* orderSummary.css */
:host {
--slds-c-card-color-background: var(--slds-g-color-surface-container-1);
display: block;
}
.total {
color: var(--slds-g-color-on-surface-2);
padding: var(--slds-g-spacing-2) 0;
}
.total--over-budget {
color: var(--slds-g-color-error-1);
}
Style your own elements with global hooks; style a base component by setting its component hooks on
:hostor on the element.Utility classes (
slds-var-p-horizontal_medium,slds-grid,slds-text-heading_small) are still the right way to do layout and spacing — they are not what "no class overrides" means.Shared styles go in a style-only module:
import shared from 'c/sharedStyles'; export default class OrderSummary extends LightningElement { static stylesheets = [shared]; }:hostis the component root; there is no/deep/, no::shadow, and styling another component's insides is not supported — pass a property or a slot instead.
3. Migration checklist for an existing component
- No
--lwc-*token left in any.cssfile - No selector reaching into an SLDS internal class (
.slds-button__icon,.slds-card__header-link, anything with__) - Every colour, spacing and font size is a hook or a utility class, not a hex value or a pixel literal
- Base components used where they exist, instead of hand-rolled markup styled to look like them
-
npx @salesforce-ux/slds-linter@latest lint force-appis clean (--fixapplies the mechanical ones) - The component is checked in both the classic and the Cosmos theme, and in dark mode if the org enables it
Add the linter to CI next to ESLint:
"scripts": {
"lint:slds": "slds-linter lint force-app/main/default/lwc",
"lint:slds:report": "slds-linter report -o reports force-app/main/default/lwc"
}
The report command writes slds-linter-report.sarif, which build systems and the SARIF viewer read directly.
4. Accessibility rules that are not optional
- Every icon-only
lightning-button-iconhasalternative-text; everylightning-iconthat conveys meaning hasalternative-text, and decorative ones say so. - Every input has a
label.variant="label-hidden"hides it visually and keeps it for screen readers — an empty label is a bug, not a style. - Errors are announced: put the message in a container with
role="alert"so it is read when it appears, and point the user at the field that failed. - Focus is managed on anything that opens or replaces content: after opening a modal (
lightning/modal), focus moves into it; after closing, focus returns to the trigger. - Keyboard: anything clickable is a
buttonor hastabindex="0"pluskeydownhandling. Adivwithonclickis unreachable for keyboard users. - Colour is never the only signal — pair the colour with an icon or text.
- Test it: the sa11y Jest matcher (
await expect(element).toBeAccessible()) in every component test, plus one keyboard-only pass through the main flow. Setup insalesforce-frontend-testing.
5. Loading, empty and error states
A component is not finished until all four states render:
| State | Pattern |
|---|---|
| Loading | lightning-spinner inside a position: relative container, or the base component's own loading state |
| Empty | An illustration or a short line plus the action that fixes it — never a blank card |
| Error | Flattened message inline near the action, role="alert", with a reference the user can quote |
| No access | Say the user lacks access rather than showing an empty list; the Apex method should distinguish the two |