In 2023, Salesforce plans to update colors in our Lighting UI to be more accessible to people with low vision and to comply with Web Content Accessibility Guidelines (WCAG) for non-text color contrast and text color contrast. WCAG is a modern accessibility standard required by numerous governing bodies around the world.

To do this, we will be updating the platforms on which our Lightning UI is built: Salesforce Lightning Design System (SLDS) and Base Lightning Components (both the Aura and Lightning Web Component versions). In these platforms, we will be updating components, design tokens, styling hooks, and icons. These changes will not only show up in Salesforce products, such as Sales Cloud and Service Cloud, but they will also show up in any custom UI that you may have created with SLDS or Base Lightning Components.

For more details and visual examples of the updates, please take a look at the Salesforce Admin and News blog posts.

What is the reason for the update?

With the current colors in Salesforce, low-vision users struggle to recognize key UI elements, which not only frustrates them, but also prevents them from adopting Salesforce. In addition, Salesforce and its customers face key compliance issues because an increasing number of governments around the world, including the European Union (EU), require color contrast in accordance with WCAG 2.1. WCAG 2.1 has required companies’ websites to use text that meets a 4.5:1 color contrast from its background and functional non-text elements that meet a 3:1 color contrast. Increasing our color contrast to meet these standards will allow us to provide a better experience for low-vision users and allow companies who use our products to avoid hefty accessibility fines.

When is the update happening?

All icons will be updated as part of the Summer ’23 release. Select record homepages including the LWCs embedded on the pages will update as part of the Summer ’23 release. All other pages, SLDS, and Lightning base components will be updated as part of the Winter ’24 release.

What do you need to do?

If you have downloaded Salesforce icons and picked out specific icons to use as static resources, make sure that you update those with the new icons. If you are using our SLDS NPM package, please update that package to the latest version to see the changes. If you have custom pages developed with SLDS, see which of the scenarios below apply to your codebase and make changes accordingly.

1. Base Lightning/Aura component

You use a Lightning component without any additional overrides. Your code might look like Example 1 below.

What do you need to do?

1. Nothing. Color updates happen for free as Lightning Base Components implements a SLDS blueprint.
2. Exceptions apply to a few components below.

Example 1

2. Custom component with SLDS blueprint

You use a custom component that implements a SLDS blueprint and only use SLDS classes for styling. Your code might look like Example 2 below.

What do you need to do?

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

Example 2

3. Custom component with partial SLDS blueprint

Similar to 2. Custom component with SLDS blueprint, but in this case, you use a custom component that partially implements an SLDS blueprint or uses more than SLDS classes for styling. Your code might look like Example 3 below.

What do you need to do?

1. You may need to update any colors in your custom CSS if you see visual regressions.
   1. If a Lightning base component exists for that blueprint and variant, we recommend replacing your custom component with the Lightning base component.
      1. If you need to customize component styling, we recommend using the new --slds styling hooks for any hardcoded color values. If the hardcoded color value does not have an exact match in terms of styling hooks, then you’ll want to consider using the closest matching styling hook.
   2. You may want to check for sufficient color contrast for the component before updating the hardcoded value to a styling hook.
2. Color changes to SLDS classes happen for free. Because changes are scoped to color, these classes should otherwise continue to function as expected otherwise.

Example 3

In this case, the custom CSS class .my-class overrides a value from .slds-button_neutral. Not only does this value need to get updated to have better contrast, but the entire implementation would also be more maintainable if it were replaced with a Lightning base component and then 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 closest styling hook available.

4. Custom component with SLDS tokens or classes

You are using a custom component that either directly uses SLDS tokens within custom CSS or uses SLDS classes in the markup. Your code might look like Example 4 below.

What do you need to do?

1. You may need to replace tokens that you are using in custom CSS with the relevant global styling hooks as necessary.
   1. Refer to Example 4 below.

Example 4

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 is aligned with the SLDS Button blueprint.

5. Custom component with custom tokens

You are using a custom component that uses custom tokens. Your code might look like Example 5 below.

What do you need to do?

We recommend replacing custom tokens with SLDS styling hooks where possible. When using styling hooks, be sure to use hooks that have the right semantic context. For example, a hook like --slds-g-color-border-base-1 should only be used for borders. This will help ensure 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.

Example 5

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.

6. Custom component with hard-coded values

You are using 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.

What do you need to do?

1. 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.

7. Base component with --lwc override

You are using a base Lightning or Aura component and are overriding a --lwc token to customize the style of one or more components. Your code might look like Example 7.

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.

What do you need to do?

1. Check to see if you are overriding and --lwc tokens for any of these components.
   1. Replace the --lwc token that is being overridden with the updated --slds styling hook introduced.

Example 7

In this example, overriding —lwc-colorBorder to red turns all the button borders red. This component variant has been updated by the SLDS team to use a global styling hook, and 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.

Best practices

• Replace hard-coded color values with global styling hooks where possible (hard-coded colors values are okay as fallback values).
• Replace design tokens with global styling hooks where possible.
• Replace --lwc styling hooks with global styling hooks.
• Pick styling hooks that correspond to the context of use. For example, when replacing the hard-coded value of #747474 that is used for a border with a styling hook, there are two alternatives to choose from: --slds-g-color-border-base-4 or --slds-g-color-neutral-base-50. It is recommended to use --slds-g-color-border-base-4 for the CSS styling context of “border” rather than --slds-g-color-neutral-base-50.
• Use var(..) statements and put hard-coded color values as backup in case a legacy browser cannot read the styling hook or design token. This is optional.
  • Example: background: var(—slds-g-color-neutral-base-50, #747474);
• Try to make your color customizations meet WCAG 2.1 text and non-text color contrast standards.

More resources

• Salesforce Winter ’24 Release Note: See Improved Color Contrast in UI Elements
• Salesforce Winter ’24 Release Note: Use Global Color Styling Hooks to Match Color-Contrast Changes
• Read more on the Salesforce Lightning Design System – Accessibility Color Contrast Migration Guide
• For in-depth information, examples, and user guides, visit the Admin blog

About the author

Timothy Yeh is a Product Manager for Design Systems at Salesforce, focused on helping customers build higher quality UI quicker by providing robust systems of patterns.