Salesforce Lightning Design System (SLDS) is a CSS framework that provides the look and feel of Lightning Experience. SLDS includes styles, themes, branding, and customizations for Lightning Experience. Use SLDS styles to give your custom Lightning web components a UI that is consistent with Salesforce. And best of all, SLDS just works with Lightning components running in Lightning Experience.
In Spring ’25, we introduced SLDS 2. 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 SLDS 2 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.
Tip
SLDS Linter is the latest code analysis tool that helps smooth your org’s transition to SLDS 2 and future-proofs your code. SLDS Linter provides many advantages over our previous tool, SLDS Validator. SLDS Linter is easier to set up, offers increased automation, and contains a more robust library of rules reflecting the new SLDS 2 styling guidelines.
Use SLDS Linter 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 make suggested fixes to your code and apply those suggestions in bulk across your repository.
For more information, see SLDS Linter on the SLDS 2 site.
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 its default theme, Salesforce Cosmos. With SLDS Validator, you get:
SLDS Validator helps you 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. To learn more, read the SLDS Validator developer guide.
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.
Note
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.
1<template>
2 <lightning-button
3 label="Submit"
4 title="submit"
5 onclick={handleSubmit}
6></lightning-button>
7 <lightning-button
8 variant="brand"
9 label="Cancel"
10 title="cancel"
11 onclick={handleCancel}
12 class="slds-m-left_medium"
13 ></lightning-button>
14</template>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.
Important
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.
To further customize your code, create your own custom CSS classes instead of overriding SLDS classes. For example, don’t target .slds-input because 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. For example, you can apply SLDS styling to a standard button element in your component.
1<button class="slds-button">Click here</button>What if you want different padding in your button? You can’t override the slds-button class because Salesforce doesn’t support that.
This example shows the correct way to get the styling you want by creating your own custom style with its value set using an SLDS global styling hook. In the default SLDS themes, the --slds-g-spacing-4 styling hook is equivalent to 16px or 1rem in most browsers. The example follows our recommendation of providing a fallback value when setting CSS variables to accommodate all environments where a component can run. The --lwc-spacingMedium property is a fallback value for SLDS 1 themes. The static value 1rem is a fallback value for an environment without SLDS.
1/* DON’T DO THIS */
2.slds-button {
3 padding: 16px;
4}
5
6/* Do this */
7.my-button-padding {
8 padding: var(--slds-g-spacing-4, var(--lwc-spacingMedium, 1rem));While working with SLDS 2 global styling hooks, always assign an SLDS 1 fallback value. To find the correct fallback value, refer to our documentation on our SLDS 1 and SLDS 2 websites. Search for the component type or the styling hook to determine appropriate values.
Tip
Apply your styling incrementally. In this example, apply the slds-button class and your my-button-padding class in the class attribute.
1<button class="slds-button my-button-padding"></button>Practice good CSS habits and don’t overload a selector. Here’s an example of overloaded selectors.
1/* DON’T DO THIS */
2button.button {
3 ...;
4}
5.card > * {
6 ...;
7}
8.button {
9 margin-bottom: 18px !important;
10}
11body.container > div.sidebar > article.card {
12 ...;
13}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. For more information, see Work with Lightning Base Components.
Use utilities such as grid and spacing classes for layout. When you add new functionality to the component, search our SLDS 1 and SLDS 2 websites 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.
1<template>
2 <h1 class="slds-text-heading_large">SLDS Example</h1>
3 <div class="slds-p-top_medium">
4 <p>Hello!</p>
5 </div>
6</template>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
Release Preview
j