LWC CSS Standards

SASS/SCSS usage, CSS custom properties, SLDS integration, scoped styles, and style organization for Lightning Web Components

Category: Salesforce
Tags: lwc standards css scss sass slds salesforce

CSS Standards

Styling Priority and Decision Order

Usage: Start with platform primitives, then move toward custom styling only when needed.

Priority Order:

  1. Use Lightning components first - lightning-button, lightning-layout, lightning-input, etc.
  2. Use SLDS classes as fallback - When Lightning components don't exist or don't meet specific requirements
  3. Use custom CSS last - Only when neither Lightning components nor SLDS classes meet requirements

Guidelines:

  • Prefer Lightning components over building custom components with SLDS classes
  • Use SLDS utility classes for spacing, alignment, etc. when Lightning components don't provide the needed functionality
  • Only create custom CSS when Lightning components and SLDS classes don't meet requirements
  • Follow SLDS naming conventions when using SLDS classes directly
  • Review current SLDS guidance before introducing new custom patterns

Examples:

<!-- Good: Use Lightning components (preferred) -->
<lightning-button variant="brand" label="Click Me"></lightning-button>

<lightning-layout>
    <lightning-layout-item size="12" medium-size="6" large-size="4">
        Content
    </lightning-layout-item>
</lightning-layout>

<lightning-input label="Account Name" value={accountName}></lightning-input>

<!-- Acceptable: Use SLDS classes when Lightning components don't meet requirements -->
<button class="slds-button slds-button_brand">
    Click Me
</button>

<p class="slds-text-align_center slds-m-vertical_medium">
    Content
</p>

<!-- Bad: Building custom button when lightning-button exists -->
<button class="slds-button slds-button_brand" onclick={handleClick}>
    Click Me
</button>
<!-- Should use: <lightning-button variant="brand" label="Click Me" onclick={handleClick}></lightning-button> -->

<!-- Bad: Using slds-grid when lightning-layout exists -->
<div class="slds-grid slds-gutters">
    <div class="slds-col">Content</div>
</div>
<!-- Should use: <lightning-layout> with <lightning-layout-item> -->

SASS/SCSS Usage

Usage: All component styles should be written in SASS/SCSS (source files) and placed in the __styles__ folder within the component directory. SASS/SCSS files compile to CSS files that are stored in the main component directory.

Guidelines:

  • Use SCSS syntax (preferred) or SASS syntax for source files
  • Place all SASS/SCSS source files in the __styles__ folder
  • Main style file should be named componentName.scss
  • Use SASS features (variables, mixins, nesting, etc.) appropriately
  • Organize related styles into partial files (_variables.scss, _mixins.scss, etc.)
  • SASS/SCSS files compile to CSS files during the build process
  • Compiled CSS files (componentName.css) are stored in the main component directory (same level as .js, .html, .js-meta.xml)
  • The compiled CSS file is what LWC uses at runtime
  • Edit SASS/SCSS source files, not the compiled CSS files
  • Follow the official Sass documentation for syntax, modules, and maintainable patterns

File Structure:

src/lwc/exampleParent/
├── exampleParent.js
├── exampleParent.html
├── exampleParent.css (compiled from __styles__/exampleParent.scss)
├── exampleParent.js-meta.xml
└── __styles__
    ├── exampleParent.scss (SASS source - edit this)
    ├── _variables.scss (SASS partial)
    └── _mixins.scss (SASS partial)

Compilation Process:

  1. Developer edits SASS/SCSS files in __styles__/ folder
  2. Build process compiles SASS/SCSS to CSS
  3. Compiled CSS file (componentName.css) is generated in main component directory
  4. LWC uses the compiled CSS file at runtime

Main Stylesheet Example:

// exampleParent.scss
@import 'variables';
@import 'mixins';

:host {
    --example-parent-text-font-size: 1rem;
    --example-parent-text-font-weight: 700;
    --example-parent-text-line-height: 1.5;
}

:host h1 {
    font-size: var(--example-parent-text-font-size, 2rem);
    font-weight: var(--example-parent-text-font-weight, 700);
}

CSS Custom Properties

Usage: Use CSS custom properties (CSS variables) for theming and dynamic styling.

Guidelines:

  • Use component prefix for custom properties: --example-component-name
  • Define custom properties in :host selector
  • Provide default values
  • Use descriptive names
  • Can be defined in SASS variables and converted to CSS custom properties

Examples:

// Using SASS variables that become CSS custom properties
:host {
    --example-child-color-background: #{$action-color-primary};
    --example-child-color-border: #{$action-color-primary};
    --example-child-color-background-hover: #{$action-color-primary-hover};
    --example-parent-text-font-size: 1rem;
    --example-parent-text-font-weight: 700;
    --example-parent-text-line-height: 1.5;
}

Or using pure CSS custom properties:

:host {
    --example-child-color-background: #0070d2;
    --example-child-color-border: #0070d2;
    --example-child-color-background-hover: #005fb2;
    --example-parent-text-font-size: 1rem;
    --example-parent-text-font-weight: 700;
    --example-parent-text-line-height: 1.5;
}

JavaScript Usage:

setColors() {
    const component = this.refs.childComponent;
    if (component) {
        component.style.setProperty('--example-child-color-background', this.customColor);
    }
}

Scoped Styles

Usage: All SASS/SCSS is automatically scoped to the component. Use :host selector for component-level styles and align with official LWC CSS scoped styles guidance.

Guidelines:

  • Use :host for component-level styles
  • Use element selectors for child elements
  • Avoid global styles (use :host instead)
  • Use :host(.class) for conditional component styles
  • Take advantage of SASS nesting for better organization

Examples:

// Good: Component-level styles
:host {
    display: block;
    padding: 1rem;

    // Good: Conditional component styles using nesting
    &.custom-class {
        background-color: #f3f3f3;
    }

    // Good: Child element styles using nesting
    h1 {
        font-size: 2rem;
        margin-bottom: 1rem;
    }

    // Good: SLDS integration using nesting
    .slds-button {
        margin-top: 1rem;
    }
}

Alternative (without nesting):

// Good: Component-level styles
:host {
    display: block;
    padding: 1rem;
}

// Good: Conditional component styles
:host(.custom-class) {
    background-color: #f3f3f3;
}

// Good: Child element styles
:host h1 {
    font-size: 2rem;
    margin-bottom: 1rem;
}

// Good: SLDS integration
:host .slds-button {
    margin-top: 1rem;
}

SASS/SCSS Organization

Guidelines:

  • Organize SASS/SCSS by component sections
  • Group related styles together
  • Use SASS partials (_filename.scss) for reusable code (variables, mixins)
  • Use @import to include partials in main stylesheet
  • Use comments to separate sections
  • Follow consistent formatting
  • Use nesting appropriately (max 3-4 levels deep)

Example Structure:

// Main stylesheet: exampleParent.scss
@import 'variables';
@import 'mixins';

// Component host styles
:host {
    display: block;

    // Typography
    h1 {
        font-size: 2rem;
    }

    p {
        font-size: 1rem;
    }

    // Layout
    .container {
        display: flex;
        flex-direction: column;
    }

    // Interactive elements
    button {
        padding: 0.5rem 1rem;

        &:hover {
            background-color: #f3f3f3;
        }
    }

    // Utility classes
    .hidden {
        display: none;
    }
}

Partial Files:

// _variables.scss
$color-primary: #0070d2;
$color-secondary: #16325c;
$spacing-small: 0.5rem;
$spacing-medium: 1rem;

// _mixins.scss
@mixin button-variant($color) {
    background-color: $color;
    border-color: $color;

    &:hover {
        background-color: darken($color, 10%);
    }
}

SASS/SCSS Best Practices

  • Use Lightning components first, then SLDS classes, then custom CSS
  • Use CSS custom properties for theming
  • Keep SASS/SCSS scoped to component
  • Use :host for component-level styles
  • Organize SASS/SCSS logically with partials
  • Use SASS variables and mixins for reusability
  • Use meaningful class names
  • Avoid deep nesting (max 3-4 levels)
  • Use comments to organize sections
  • Place all style files in __styles__ folder
  • Use SCSS syntax (preferred) or SASS syntax consistently

Change History

Version 1.0 - 2026-03-26

  • Added initial version history tracking for this document.

Last Updated: 2026-03-26 Version: 1.0