Migration Guide

1. Base Lightning Component

You use a Lightning web component or an Aura component without any additional overrides. Here's an example of a custom Lightning web component.

<!-- Markup -->
<template>
  <lightning-button>Save</lightning-button>
</template>

Nothing. Color updates happen for free as the base Lightning components implement SLDS blueprints.

2. Custom Component with SLDS Blueprint

You use a custom component that implements a SLDS blueprint and only use SLDS classes for styling. Here's an example of a custom Lightning web component.

<!-- myComponent.html -->
<template>
  <button class="slds-button slds-button_neutral">Save</button>
</template>

Nothing. Color updates happen for free if your component exactly implements an SLDS blueprint.

3. Custom Component with Partial SLDS Blueprint

This scenario is similar to 2. Custom Component with SLDS Blueprint, but you use a custom component that partially implements an SLDS blueprint or uses more than SLDS classes for styling. Here's an example of a custom Lightning web component.

<!-- Markup -->
<template>
  <button class="slds-button slds-button_neutral my-class">Save</button>
</template>

/* CSS */
.my-class {
  color: #ccc; <-- This value needs to get updated to meet WCAG guidelines
  margin-left: 1rem;
}

You may need to update colors in your custom CSS if you see visual regressions.

1. If a base Lightning component exists for that blueprint and variant, we recommend replacing your custom component with the base Lightning component.

2. If you need to customize component styling, we recommend that you use --slds styling hooks for any hardcoded color values. If the hardcoded color value doesn't have an exact match in styling hooks, consider using the styling hook that has the closest matching color value.

3. You may want to check for sufficient color contrast for the component before updating the hardcoded value to a styling hook. The Stark Accessibility Checker has a free color contrast tool that's available as a browser extension in multiple browsers. For Chrome, get the extension at the chrome web store.

4. Color changes to SLDS classes happen for free. Because changes are scoped to color, these classes should otherwise continue to function, as expected.

In this example, the custom CSS class .my-class overrides a value from .slds-button_neutral. You should update the value associated with the custom class to have better color contrast. The entire implementation would also be more maintainable if you replace it with a base Lightning component and use the --slds-c-button-text-color styling hook to make an accessible override.

Note: If no styling hook exists for the hard coded value, we recommend using the styling hook that has the closest matching color value.

<!-- Fixed Markup -->
<template>
  <lightning-button class="slds-m-left_medium">Save</lightning-button>
</template>

/* Fixed CSS */
:host {
  --slds-c-button-text-color: var(--slds-g-color-neutral-base-80, #C9C9C9);
}

4. Custom Component with SLDS Tokens or Classes

You use a custom component that either directly uses SLDS tokens within custom CSS or uses SLDS classes in the markup. Here's an example of a custom Lightning web component.

<!-- Markup -->
<template>
  <button class="my-button">Save</button>
</template>

/* CSS */
.my-button{
  border-color: var(--lwc-colorBorder);
}

You may need to replace tokens in custom CSS with the relevant global color styling hooks, as necessary.

In this example, the token t(colorBorder) is intended for decorative borders like cards and dividers. It should be replaced with a styling hook that's aligned with the SLDS Button blueprint.

/* Fixed CSS
*  Closest matching styling hooks for t(colorBorder)
*/
.my-button{
  border-color: var(--slds-g-color-neutral-base-50, #747474);
}

5. Custom Component with Custom Tokens

You use a custom component that uses custom Aura design tokens. Here's the definition of a custom Aura design token and a custom component's CSS that references the custom token.

<!-- Custom Aura token -->
<aura:tokens>
  <aura:token name="myBackgroundColor" value="#f4f6f9"/>
</aura:tokens>
<!-- Markup -->
<template>
  <div class="my-div">...</div>
<template>

/* CSS */
.my-div{
  background-color: t(myBackgroundColor);
}

/* or */

.my-div{
  background-color: var(--c-myBackgroundColor);
}

We recommend replacing custom design tokens with SLDS styling hooks, where possible. When using styling hooks, use a hook that has the right semantic context. For example, a hook such as --slds-g-color-border-base-1 should only be used for borders. This approach ensures that your product remains consistent with Salesforce's styling as future color updates occur.

If you must keep your custom token for whatever reason, double check that your custom token hasn't experienced any visual regressions.

In this example, the token t(myBackgroundColor) is using an outdated color value from SLDS. The current Lightning visual language no longer uses this color. The custom token should be replaced with the closest color from the list of styling hooks. In this example, slds-g-color-neutral-base-95: #f3f3f3 is the closest matching SLDS Styling hook.

/* CSS Fixed */
.my-div{
  background-color: var(--slds-g-color-neutral-base-95, #f3f3f3);
}

6. Custom Component with Hard-coded Values

You use a custom component that uses a hard-coded color value like #444 or rgb(68,68,68). Your code might look like example 3 above.

We recommend replacing hard-coded colors with styling hooks if an analogous color exists. When selecting tokens, be sure to use semantic tokens in ways that preserve their meaning. For example --slds-g-color-border-base-1 should only be used as the border color of form elements. If you want to keep your hard-coded color value, verify that these colors have not experienced any visual regressions.

Note: Fallback values can remain as hard-coded color values. The var() function accepts two arguments: a CSS custom property and an optional fallback value. In this example, --slds-c-badge-color-background is the first argument, the CSS custom property, and #ECEBEA is the second argument, the fallback value.

var(--slds-c-badge-color-background, #ECEBEA)

7. Base Component with --lwc override

You use a base Lightning component and you're overriding a --lwc token to customize the style of one or more components. Here's an example of a custom Lightning web component.

<!-- Markup -->
<template>
  <lightning-radio-group name="radioGroup"
      label="Radio Group"
      options={options}
      value={value}
      type="button"></lightning-radio-group>
</template>

/* CSS */
:host {
  --lwc-colorBorder: red;
}

NOTE: This is not a recommended way to customize components and there is no guarantee that customizations made in this way will continue to function.

1. Check if you are overriding and --lwc tokens for any of these components.

2. Replace each overridden --lwc token with a --slds styling hook.

In this example, overriding --lwc-colorBorder to red turns all the button borders red. The SLDS team updated this component variant to use a global color styling hook so this override will stop working. In this case, simply use --slds-g-color-border-base-4 under the selector scope to override the border color.

// CSS fixed
:host {
  --slds-g-color-border-base-4: red;
}

8. UI Namespace Components

You are using ui components such as ui:inputText or ui:menu.

UI namespace components were deprecated and should be replaced by their counterparts from the lightning namespace. See here for more info.

Summary

• Check for visual regressions by looking at pages that contain custom components.

• Replace hard-coded color values with global color styling hooks, where possible.

• Replace design tokens with global color styling hooks, where possible.

• Replace --lwc styling hooks with global color styling hooks.

• If there's no exact styling hook match for the hard-coded color value, use the closest available matching styling hook.

• Pick styling hooks that correspond to the context of usage. For example, when replacing the hard-coded value of #747474 with a styling hook, there are two alternatives to choose from --slds-g-color-border-base-4 or --slds-g-color-neutral-base-50. We recommend that you use --slds-g-color-border-base-4 for the CSS styling context of "border" rather than --slds-g-color-neutral-base-50.

• Use other categories of Styling hooks also beyond color Styling hooks for the hardcoded values.

• We recommend using a hardcoded fallback value in var(..) statement in case a legacy browser cannot read the styling hook or design token. This is optional.

  Example: var(--slds-g-color-neutral-base-50, #747474);

• We recommend any color customizations that you make meet WCAG 2.1 text and non-text color contrast standards.