Style Components with Lightning Design System
Salesforce Lightning Design System (SLDS) is a CSS framework that provides a look and feel that’s consistent with Lightning Experience. Use SLDS styles to give your custom Lightning web components a UI that is consistent with Salesforce, without having to reverse-engineer our styles. And best of all, it just works with Lightning components running in Lightning Experience and in the Salesforce mobile application.
Interactive base component examples are available in the Component Reference.
With SLDS Validator for VS Code, you get validation with SLDS tokens and utility classes, along with syntax highlighting and code completion. SLDS Validator extension also simplifies working with base Lightning 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.
If you installed the Salesforce Extension Pack, SLDS Validator is automatically installed with it. For more information, see SLDS Validator for VS Code.
Base components in the lightning namespace use Lightning Design System styling. Many base components are built from SLDS component blueprints. A blueprint is framework-agnostic, accessible HTML and CSS. A few examples include the lightning-accordion, 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.
When styling your components, don’t depend on the internal markup or CSS classes of base Lightning components, as they can change in future releases. 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 base Lightning component, first check the Component Reference to see whether the component has design variations. 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, consider styling hooks. For more information, see Style Components Using Lightning Design System Styling Hooks.
If styling hooks don’t work for your use case, try design tokens with global access.
Since Winter '24, we recommend that you use global color styling hooks instead of design tokens, where possible, to align with the Web Content Accessibility Guidelines (WCAG) 2.1 color contrast standards. See Lightning Design System: Migration Guide.
If the global design tokens don’t work, create a custom CSS class instead of overriding an SLDS class. Create a 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 live 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.
Practice good CSS habits and don’t overload a selector.
To build a Lightning web component, compose it by combining smaller 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