LWC CSS and Styling
LWC components render inside a shadow DOM by default. Component
CSS is scoped to the component — it does not bleed in or out.
SLDS classes work everywhere because the framework injects them
globally; everything else stops at the shadow boundary. This is
the single fact that determines every styling decision.
The typical confusion: a developer wants to change the background
color of a lightning-button. They write
lightning-button .slds-button { background: red; } and see no
effect. The reason is the .slds-button class lives inside the
button's shadow DOM. Five years ago the answer was a /deep/
selector or ::shadow, both since deprecated. The current answer
is SLDS styling hooks — --slds-c-button-color-background: red — which the base components consume from the consumer's CSS
custom property cascade.
For cases where there is no styling hook for the property you
need, the toolbox has three more options: ::part() (where
the base component exposes a part), light DOM
(static renderMode = 'light'), or a slot (let the consumer
render their own element). Each has tradeoffs. Reaching for
!important or for the SLDS internal class name is the wrong
answer almost always — the next SLDS upgrade renames the class
and the styling vanishes.
Recommended Workflow
- Read the component's "Styling Hooks" tab in the Component
Library before writing CSS. Most base components document a
list of
--slds-c-*-color-*, --slds-c-*-spacing-*,
--slds-c-*-radius-* properties they consume. If the property
you need has a hook, set it and stop.
- If no hook exists, check
::part() exposure. Some base
components (newer ones especially) expose internal elements via
::part(name). Style them with
lightning-foo::part(bar) { ... }.
- For your own components, prefer SLDS classes over hand-rolled
styles.
class="slds-card" is admin-portable, theme-aware,
and survives SLDS upgrades. Custom CSS is a maintenance ratchet.
- Use design tokens (
--lwc-colorBrand, --slds-g-color-*)
instead of literal hex codes. The user might have High
Contrast mode on, the org might be themed via
LightningExperienceTheme, the page might be in a community
with a different brand color.
- Reach for light DOM only when shadow DOM is the bottleneck.
static renderMode = 'light' removes the shadow boundary —
the component participates in global CSS. It also forfeits
encapsulation; another component's .button rule will hit
yours. Use for small layout components, never for shared base.
- Never use
!important in a base-component override. It
binds the override to the current SLDS internal-class name.
When SLDS updates, your override fails silently and the user
sees the default style.
- Write CSS in
*.css next to the JS, not inline style=.
Inline styles bypass the design-token cascade and are harder
to override per-theme.
What This Skill Does Not Cover
| Topic |
See instead |
SLDS icon usage and lightning-icon |
lwc/lwc-slds-icons |
| Aura styling |
Aura is deprecated for new development |
| Custom Lightning App theming |
admin/branding-themes |
| Experience Cloud / Community CSS |
lwc/lwc-community-styling |
1---2name: lwc-css-and-styling3description: "Styling LWC components — SLDS design tokens, --slds-c-* styling hooks, scoped CSS via shadow DOM, ::part() for restyling base components, light DOM (lwc:render-mode='light'), why CSS doesn't pierce the shadow boundary, !important vs specificity, and SLDS upgrades breaking hand-rolled selectors. NOT for app-scope theming or SLDS 2 hook migration — use lwc/lwc-styling-hooks. NOT for picking shadow vs light DOM — use lwc/lwc-shadow-vs-light-dom-decision."4category: lwc5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Operational Excellence8 - Performance9triggers:10 - "lwc style base component slds hook"11 - "--slds-c-button-color-background lwc"12 - "lwc shadow dom css does not pierce"13 - "lwc light dom render mode shared styles"14 - "lwc ::part() restyle internal element"15 - "lwc styling hooks vs deep selector"16 - "slds design tokens lwc theming"17tags:18 - css19 - slds20 - shadow-dom21 - styling-hooks22 - design-tokens23inputs:24 - "Which base component or slot needs custom styling"25 - "Whether the component is in a Lightning Page (themed) or standalone"26 - "Whether the component must theme dynamically (dark mode, brand variants)"27outputs:28 - "Decision: SLDS hook (--slds-c-*) vs ::part() vs light DOM vs slot"29 - "Component CSS file using design tokens, no !important, no internal-selector hacks"30 - "Theming pattern that survives SLDS version upgrades"31dependencies: []32version: 1.0.033author: Pranav Nagrecha34updated: 2026-05-0535metadata:36 source: https://skillmd.com/skills/pranavnagrecha/lwc-css-and-styling37---3839# LWC CSS and Styling4041LWC components render inside a shadow DOM by default. Component42CSS is scoped to the component — it does not bleed in or out.43SLDS classes work everywhere because the framework injects them44globally; everything else stops at the shadow boundary. This is45the single fact that determines every styling decision.4647The typical confusion: a developer wants to change the background48color of a `lightning-button`. They write49`lightning-button .slds-button { background: red; }` and see no50effect. The reason is the `.slds-button` class lives inside the51button's shadow DOM. Five years ago the answer was a `/deep/`52selector or `::shadow`, both since deprecated. The current answer53is **SLDS styling hooks** — `--slds-c-button-color-background:54red` — which the base components consume from the consumer's CSS55custom property cascade.5657For cases where there is no styling hook for the property you58need, the toolbox has three more options: `::part()` (where59the base component exposes a part), light DOM60(`static renderMode = 'light'`), or a slot (let the consumer61render their own element). Each has tradeoffs. Reaching for62`!important` or for the SLDS internal class name is the wrong63answer almost always — the next SLDS upgrade renames the class64and the styling vanishes.6566## Recommended Workflow67681. **Read the component's "Styling Hooks" tab in the Component69 Library before writing CSS.** Most base components document a70 list of `--slds-c-*-color-*`, `--slds-c-*-spacing-*`,71 `--slds-c-*-radius-*` properties they consume. If the property72 you need has a hook, set it and stop.732. **If no hook exists, check `::part()` exposure.** Some base74 components (newer ones especially) expose internal elements via75 `::part(name)`. Style them with76 `lightning-foo::part(bar) { ... }`.773. **For your own components, prefer SLDS classes over hand-rolled78 styles.** `class="slds-card"` is admin-portable, theme-aware,79 and survives SLDS upgrades. Custom CSS is a maintenance ratchet.804. **Use design tokens (`--lwc-colorBrand`, `--slds-g-color-*`)81 instead of literal hex codes.** The user might have High82 Contrast mode on, the org might be themed via83 `LightningExperienceTheme`, the page might be in a community84 with a different brand color.855. **Reach for light DOM only when shadow DOM is the bottleneck.**86 `static renderMode = 'light'` removes the shadow boundary —87 the component participates in global CSS. It also forfeits88 encapsulation; another component's `.button` rule will hit89 yours. Use for small layout components, never for shared base.906. **Never use `!important` in a base-component override.** It91 binds the override to the current SLDS internal-class name.92 When SLDS updates, your override fails silently and the user93 sees the default style.947. **Write CSS in `*.css` next to the JS, not inline `style=`.**95 Inline styles bypass the design-token cascade and are harder96 to override per-theme.9798## What This Skill Does Not Cover99100| Topic | See instead |101|---|---|102| SLDS icon usage and `lightning-icon` | `lwc/lwc-slds-icons` |103| Aura styling | Aura is deprecated for new development |104| Custom Lightning App theming | `admin/branding-themes` |105| Experience Cloud / Community CSS | `lwc/lwc-community-styling` |