Style Components with Lightning Design System

Salesforce Lightning Design System (SLDS) is a CSS framework that provides the look and feel of Lightning Experience. Use SLDS styles to give your custom Lightning web components a UI that is consistent with Salesforce. And best of all, it just works with Lightning components running in Lightning Experience and in the Salesforce mobile application.

In Spring ’25, we introduced SLDS 2 (beta). This new SLDS architecture prioritizes CSS custom properties. We offer new tools that make it easier to validate your components against SLDS rules and migrate components to SLDS 2. The new site has a Transition to SLDS 2 guidebook to get your org up and running with SLDS 2.

The lightningdesignsystem.com site now presents SLDS 2 content. The SLDS 1 content is available at v1.lightningdesignsystem.com.

SLDS Validator for VS Code scans your component markup and CSS, validates it against a set of SLDS guidelines, and provides recommendations to improve your code. The SLDS Validator extension simplifies working with Salesforce Lightning Design System (SLDS) 1 and SLDS 2.

Use SLDS Validator to help get your components ready for SLDS 2 and the Salesforce Cosmos theme. With SLDS Validator, you get:

  • SLDS 1 and SLDS 2 support
  • Validation with recommended styling hooks and utility classes
  • Syntax highlighting
  • Code completion
  • Context awareness
  • Bulk report generation

SLDS Validator enables you to transition your component styling from legacy SLDS 1 design tokens to global styling hooks, correct the BEM syntax used in SLDS classes, and more. If you’re going to stick with SLDS 1 for now, SLDS Validator can help with that too.

SLDS Validator also simplifies working with Lightning base components. You can enable SLDS validation for mobile, color contrast detection, and more. To install SLDS Validator, go to the extension page on Visual Studio Marketplace.

When you install the Salesforce Extension Pack, SLDS Validator is automatically installed, so you might already have it. For more information, see SLDS Validator for VS Code.

SLDS Linter (beta) is a tool you can use to help prepare your components for use in SLDS 2. SLDS Linter analyzes your code against SLDS 2 rules. It offers suggestions on how to improve your code and make it more future-proof. SLDS Linter can also automatically fix your code and apply those suggestions in bulk across your repository.

⚠️ SLDS Linter is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

For more information, see SLDS Linter (Beta) on the SLDS 2 site.

Base components in the lightning namespace use Salesforce Lightning Design System styling. Salesforce used the SLDS component blueprints to build the base components that create visible UI elements. A blueprint is framework-agnostic, accessible HTML and CSS that defines how a component looks and its user interaction, but doesn’t provide logic. The base components do include JavaScript logic and provide attributes, events, and methods to enable you to interact with your org’s data. A few examples of base components include the lightning-accordion, lightning-button, lightning-card, and lightning-tree components.

Base components provide a class attribute so that you can add an SLDS utility class or custom class to the outer elements of the components. For example, to apply a margin utility class to the lightning-button base component, use class="slds-m-left_medium". Here it’s used to increase the margin between buttons.

Some components provide a variant attribute so that you can apply a design variation easily. For example, lightning-button has a variant attribute that you can set to base, neutral, brand, brand-outline, destructive, destructive-text, inverse, and success. These values implement the button blueprint’s variations.

When styling your components, don’t depend on the internal markup or CSS classes of Lightning base components, as they can change in future releases. To display correctly in Salesforce Lightning Design System (SLDS) 2, components whose styling depends on internal markup must migrate to global styling hooks. For more information, see Transition to SLDS 2.

Overriding base component styling isn't supported except when using documented styling hooks. See Anti-Patterns for Styling Components.

To change the styling of a Lightning base component, first check that component's documentation in the Component Reference to see if it has design variations. These can be specified with component attributes such as variant or type, for example. To change the spacing of a component, such as the alignment, padding, margin, or even its typography, use Lightning Design System utility classes.

If design variations and utility classes don’t meet your requirements, use styling hooks. For more information, see Style Components Using Lightning Design System Styling Hooks.

If utility classes and styling hooks don’t work for your use case, create a custom CSS class instead of overriding an SLDS class. Create your own class instead of targeting a class name you don’t own, since that class name can change. For example, don’t target .slds-input, as it’s part of the base component internal markup. Instead, create a custom class and pass it into the class attribute.

Custom components that run in Lightning Experience or in the Salesforce mobile application can use Lightning Design System without any import statements or static resources. Simply assign a Lightning Design System CSS class to an HTML element.

Apply your styling incrementally. In this example, instead of changing the padding of an SLDS style, you can define padding in your own style, and then apply both styles in the class attribute.

Practice good CSS habits and don’t overload a selector.

To build a Lightning web component, compose it by combining simpler lightning base components into a more complex, custom component. Try to construct your design from components like buttons and media objects. Use utilities, such as grid and spacing classes for layout. When you add new functionality to the component, search Lightning Design System for patterns that work and apply the classes to the template.

For example, use the utility classes to change your header size or add padding to your div containers.

If you can’t find a base component for your use case, find the closest SLDS blueprint to help you build your component. See Create a Component from an SLDS Blueprint.

See Also