# Style Components with Lightning Design System

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](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-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](https://www.lightningdesignsystem.com/2e1ef8501/p/8184ad-transition-to-slds-2) guidebook to get your org up and running with SLDS 2.

:::tip
The [lightningdesignsystem.com](http://lightningdesignsystem.com) site now presents SLDS 2 content. The SLDS 1 content is available at [v1.lightningdesignsystem.com](http://v1.lightningdesignsystem.com).
:::

## Analyze Component Code with SLDS Linter

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](https://www.lightningdesignsystem.com/2e1ef8501/p/012d73-slds-linter) on the SLDS 2 site.

## Analyze Component Code with SLDS Validator

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](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://lightningdesignsystem.com).

Use SLDS Validator to help get your components ready for SLDS 2 and its default theme, Salesforce Cosmos. 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 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](https://developer.salesforce.com/docs/atlas.en-us.mobile_offline.meta/mobile_offline/ux_extensions_base_component_validation.htm), color contrast detection, and more. To install SLDS Validator, go to the extension page on [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=salesforce.salesforce-vscode-slds). To learn more, read the [SLDS Validator](https://developer.salesforce.com/docs/platform/slds-validator/overview) developer guide.

:::note
When you install the [Salesforce Extension Pack](/docs/platform/lwc/guide/get-started-editor-linter-org.md), SLDS Validator is automatically installed, so you might already have it. For more information, see [SLDS Validator for VS Code](https://www.lightningdesignsystem.com/tools/validator/).
:::

## Use Lightning Base Components

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.

```html
<template>
  <lightning-button 
    label="Submit" 
    title="submit" 
    onclick={handleSubmit}
></lightning-button>
  <lightning-button
    variant="brand"
    label="Cancel"
    title="cancel"
    onclick={handleCancel}
    class="slds-m-left_medium"
  ></lightning-button>
</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](https://v1.lightningdesignsystem.com/components/buttons/#Variations).

:::important
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](https://www.lightningdesignsystem.com/2e1ef8501/p/8184ad-transition-to-slds-2).

Overriding base component styling isn't supported except when using documented styling hooks. See [Anti-Patterns for Styling Components](/docs/platform/lwc/guide/create-components-css-antipatterns.md).
:::

## Use Lightning Base Component Design Variations and Utility Classes

To change the styling of a Lightning base component, first check that component's documentation in the [Component Reference](https://developer.salesforce.com/docs/platform/lightning-component-reference/) to see if it has [design variations](/docs/platform/lwc/guide/create-components-css-variants.md). 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](https://v1.lightningdesignsystem.com/utilities/alignment/).

## Use Styling Hooks to Customize Default Styles

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](/docs/platform/lwc/guide/create-components-css-custom-properties.md).

## Apply Custom CSS Classes

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.

```html
<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.

```css
/* DON’T DO THIS */
.slds-button {
  padding: 16px;
}

/* Do this */
.my-button-padding {
  padding: var(--slds-g-spacing-4, var(--lwc-spacingMedium, 1rem));
```

:::tip
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](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2) websites. Search for the component type or the styling hook to determine appropriate values.
:::

Apply your styling incrementally. In this example, apply the `slds-button` class and your `my-button-padding` class in the `class` attribute.

```html
<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.

```css
/* DON’T DO THIS */
button.button {
  ...;
}
.card > * {
  ...;
}
.button {
  margin-bottom: 18px !important;
}
body.container > div.sidebar > article.card {
  ...;
}
```

## Create Custom Components from Base Components

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](/docs/platform/lwc/guide/base-components-overview.md).

Use utilities such as grid and spacing classes for layout. When you add new functionality to the component, search our [SLDS 1](https://v1.lightningdesignsystem.com/) and [SLDS 2](https://www.lightningdesignsystem.com/2e1ef8501/p/85bd85-lightning-design-system-2) websites for patterns that work and apply the classes to the template.

For example, use the [utility classes](https://www.lightningdesignsystem.com/2e1ef8501/p/05098e-utility-classes) to change your header size or add padding to your `div` containers.

```html
<template>
  <h1 class="slds-text-heading_large">SLDS Example</h1>
  <div class="slds-p-top_medium">
    <p>Hello!</p>
  </div>
</template>
```

## Create Custom Components from Lightning Design System Blueprints

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](/docs/platform/lwc/guide/create-components-css-slds-blueprint.md).

**See Also**

- [Lightning Design System: Global Color Styling Hooks](https://v1.lightningdesignsystem.com/accessibility/global-color-styling-hooks/)