SLDS Development Best Practices - Lightning Design System

Use these best practices to author new Aura and Lightning Web Components (LWC) with SLDS, as well as update your existing styled components. With these guidelines, you can more easily adopt future new features based on SLDS. This page includes general guidance for using SLDS, specific guidance for updating certain components and styles, resources to assist you, and any other considerations to keep in mind while styling with SLDS.

Starting in the Spring ’25 release, Salesforce is overhauling the look and feel of the Lightning UI. The changes are designed to modernize the UI and improve navigation, as well as prepare for SLDS 2, the next major version of the Salesforce Lightning Design System. Some styling solutions that were supported prior to the Spring ’25 release aren’t compatible with SLDS 2, so we’ll walk you through the most common styling hooks and practices you need to update before SLDS 2 arrives.

How to Use SLDS

SLDS gives you a great deal of control over the look and feel of your components with three supported customization layers. With each layer of customization, you have more control over a component’s individual elements, but the implementation becomes much more complex and granular. Always use the first layer of customization that works with your use case, and only use the next layer if your use case requires a more complex solution.

1. Use Lightning Base Components
With Lightning Base Components, you can customize and style each Lightning Base Component with their built-in HTML attributes. Using these components is the best way to ensure accessibility and SLDS best practices.

2. Use SLDS Blueprints
If the attributes for Lightning Base Components alone can’t meet your use-case, then you can use the SLDS Blueprints that model our Lightning Base Components. With a blueprint, you can customize and style the individual HTML elements within each component using SLDS classes. These blueprints provide framework-agnostic HTML/CSS and accessibility best practices to help adhere to the SLDS standards.

3. Use SLDS Styling Hooks
If you can’t meet your use-case by customizing the blueprint with SLDS classes, then you can use the foundational layer of customization in SLDS, Styling Hooks. Styling hooks are variables that provide CSS properties such as colors, typography, spacing, sizing, and more. If you decide to customize styling hooks for your org, closely follow the Global Styling Hook Guidance to make sure your customizations adhere to accessibility standards and SLDS best practices.

NOTE: The newest global styling hooks are only available in Lightning Experience, and are not supported for Experience Cloud sites.

Update Your SLDS Styles

SLDS best practices update regularly to meet changing accessibility and industry standards. Certain solutions that we offered previously are no longer considered “best practice,” and require an update for your site to meet current standards. With big changes coming to SLDS in the near future, including SLDS 2, now is the best time to update your SLDS styles, so that the transition doesn’t cause breaking changes to your org.

Assess Your Current Styling Solutions

Before you even touch your code, sit down and find where exactly you’re using SLDS to style your experience. The Salesforce Extension Pack for VSCode includes the Salesforce Validator 2.0 plugin, which you can use to automatically detect outdated styling hooks and get recommendations for updating them. Before you edit anything, make a note of all the places where each outdated value appears in your UI. You may discover unknown use cases, or no use cases at all.

These are the most important CSS properties to focus on. They don’t affect the document layout or CSS box model, so they’re the safest to update first.

background-color
border-color
color
border-radius
box-shadow
fill
font-size
font-weight

If any of your customization solutions are out-of-date, take the time to understand the context for the styles. Don’t blindly replace values with suggested replacements. Instead, match the semantics of how the value is used in the UI. Salesforce Validator can make recommendations, but only you know the best choice for your use case.

Update Styling Hooks

Most outdated solutions are best replaced with Global Styling Hooks, in particular the semantic styling hooks. These hooks are what power theming. Shared and component-level styling hooks aren’t supported in the new SLDS 2, so replace them with global styling hooks where you can.

NOTE: Global styling hooks are only for consuming a predetermined value defined by the Design System. Re-assigning a new value to a global styling hook inside your component causes test failures and may break your site altogether with SLDS 2.

Please review Styling Hook Guidance to understand how context is important when choosing the correct styling hook. Finding a hook based on a matching value is not enough; the context of the style must also be correct.

Aura Design Tokens and `--lwc-*` Namespace Hooks

SLDS Aura tokens and --lwc-* custom properties are deprecated. Instead, use global styling hooks. These scenarios provide a few examples demonstrating how to update your code in each use case.

Replace a Custom Property or Aura Token in a Selector that You Own

In this example, we update the background color for a custom container in both LWC and Aura CSS to use an equivalent global styling hook, but fallback on the old namespace and Aura tokens.

/* LWC CSS */
.my-custom-container {
  background-color: var(--lwc-cardColorBackground);
}

/* Aura CSS */
.THIS .my-custom-container {
  background-color: t(cardColorBackground);
}

/*  ----- Refactor to -----  */

/* Updated LWC CSS */
.my-custom-container {
  background-color: var(--slds-g-color-surface-container-1, var(--lwc-cardColorBackground));
}

/* Updated Aura CSS */
.THIS .my-custom-container {
  background-color: var(--slds-g-color-surface-container-1, t(cardColorBackground));
}

In this specific scenario, the developer might also look into replacing their custom container with the equivalent LBC component, lighting-card, that acts as a card container. Refactoring to use the LBC component would mean the developer doesn’t have to maintain and update the CSS, since the component is updated automatically.

Replace a Custom Property in a Selector that You Don’t Own

Setting --lwc-* custom properties is not supported in SLDS 2. However, if removing the custom property causes issues with your current implementation, we don’t suggest replacing it yet. The reassigned value will continue to work in legacy SLDS, but will be ignored in SLDS 2.

`--sds-*` Namespace Hooks

The --sds-* namespace hooks are deprecated in all versions of SLDS. Instead, use global styling hooks in the —slds-* namespace. If you have component-level --sds-c-* styling hooks for SLDS, update to --slds-c-* namespace.

`--slds-*` Namespace Hooks

There are several non-global styling hooks in the --slds-* namespace are not supported in SLDS 2. Salesforce Validator for VSCode flags these outdated styling hooks for you. Using a deprecated hook may eventually cause regressions once they are phased out. These scenarios provide a few examples demonstrating how to update your code in each use case.

Replace Older or Deprecated Styling Hooks

If you’re using an outdated styling hook, replace it with a supported global styling hook where possible. But never remove a deprecated hook unless you if you have tested in both SLDS and SLDS 2 experiences, and always keep both for improved backwards compatibility.

Most --slds-g-* global styling hooks are best practice to use in your code, but there are still a few unsupported in SLDS 2. If you use accessible system color global hooks directly, transition to semantic styling hooks where possible.

When researching a replacement styling hook, look for a global styling hooks that have the same semantic meaning as the value that you're replacing. For example, if you use a styling hook for border colors, narrow your search down to styling hooks just for that category. From this category, select the hook that has the closest value match to the value that you're replacing. In this example, both borders colors are using #747474.

/* Deprecated hook */
--slds-g-color-border-base-4

/* Updated hook */
--slds-g-color-border-2

Replace a Styling Hook as a Value within a Selector that You Own

Update your global styling hooks to use a semantic styling hook where possible. In this example, both background colors use #FFFFFF, but the updated CSS uses a semantic styling hook.

/* Deprecated CSS */
.my-custom-container {
  background-color: var(--slds-g-color-neutral-base-100);
}

/* Markup */
<div class="my-custom-container">...</div>

/*  ----- Refactor to -----  */

/* Updated CSS */
.my-custom-container {
  background-color: var(--slds-g-color-surface-container-1);
}

/* Markup */
<div class="my-custom-container">...</div>

Replace a Styling Hook as a Value for a Selector that You Don’t Own

Direct CSS customizations to components aren’t supported in SLDS 2. However, if removing the CSS causes issues with your current implementation, we don’t suggest replacing it yet. The reassigned value will continue to work in legacy SLDS, but will be ignored in SLDS 2.

Update Other Styling Solutions

SLDS Classes in Custom Markup

If your custom markup significantly diverges from the SLDS blueprint’s markup, you may experience breaking changes in the transition to SLDS 2. To reduce the risk, update your markup to align with the associated SLDS blueprint as closely as possible for your use case.

NOTE: If your users rely on your markup structure, any changes to your markup may cause unintended side-effects, including regressions. If you’re uncertain whether users target your markup, restrict your updates to CSS-only changes.

If your custom markup isn’t implementing SLDS blueprints correctly, update the markup to align with the associated SLDS blueprint, which will reduce any side-effects as SLDS is updated in the future

Hard-Coded Values

Replace hard-coded values with global styling hooks where possible. Hard-coded CSS values are static, and are difficult to update and adapt in the very dynamic system of SLDS. They don’t change with theming changes, so they can’t benefit from future visual design language updates, including accessibility updates and SLDS 2.

To determine what styling hook you should use to replace a hard coded value, consult the Global Styling Hooks Reference. Look for a global styling hooks that have the same semantic meaning as the value that you're replacing. For example, if you are using a styling hook to apply colors for error messages, narrow your search down to styling hooks in the "error" category. From the styling hooks category, select the global styling hook that has the closest value match to the value that you're replacing.

In this example, we replace the hard-coded background color and border radius with global styling hooks that use the same values. We also keep the hard-coded values as a fallback.

/* Hard-coded CSS */
.my-custom-card {
  background-color:#ffffff;
  border-radius: 1rem;
}

/*  ----- Refactor to -----  */

/* Updated CSS */
.my-custom-card {
  background-color: var(--slds-g-color-surface-container-1, #ffffff);
  border-radius: var(--slds-g-radius-border-4, 1rem);
}