Org Skills

SLDS 2, styling hooks and accessibility

Supporting material for lwc-development. Agents load it on demand; it ships inside the skill folder.

RawSource

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 :host or 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];
    }
    
  • :host is 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 .css file
  • 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-app is clean (--fix applies 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-icon has alternative-text; every lightning-icon that conveys meaning has alternative-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 button or has tabindex="0" plus keydown handling. A div with onclick is 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 in salesforce-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