# SLDS 2, styling hooks and accessibility

Target: Spring '26, SLDS 2 GA since Winter '26. Sources: [SLDS Linter developer guide](https://developer.salesforce.com/docs/platform/slds-linter/overview), [SLDS Linter repo](https://github.com/salesforce-ux/slds-linter), [Enhanced Lightning Experience / SLDS 2](https://help.salesforce.com/s/articleView?id=xcloud.customize_ui_enhancedlex.htm&type=5).

## 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

```css
/* 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:

  ```js
  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:

```json
"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 |
