Internal Design System Architecture Updates Go Live in Summer 24

If you’re an admin of an org with an Experience Cloud site, Lightning pages, or both. Starting in Summer ’24, we’re modifying the design system architecture to support future product innovations. Internal Design System Architecture Updates Go Live in Summer 24.

The changes Salesforce are making aren’t visible to most customers. If you customize the visual design of your pages or sites by using supported techniques, they expect these changes to have little to no impact on your customizations.

However, if your org customizes Lightning pages or Experience Cloud sites by targeting Salesforce components and CSS styles that change with the architecture updates, some visual regressions are possible. These visual regressions can range from a UI component displaying a slightly different color to layout changes in your UI.

For more details, review the SLDS Architecture Updates FAQs below.

During the Summer ’24 Release Sandbox Preview on May 10, 2024, work with your site development team or Tectonic to review the user interface. If you notice visual regressions, refer to the SLDS Architecture Updates FAQs to learn how to update the customized CSS and resolve the regressions.

Why take this action? If you customized Lightning pages or Experience Cloud sites by using unsupported techniques, visual regressions are possible.

Internal Design System Architecture Updates Go Live in Summer 24

Starting with the Summer ‘24 Release, Salesforce is modifying the internal implementations of our Lightning components, Salesforce Lightning Design System (SLDS) styles, and custom properties to support future UI changes (safe harbor).

These internal changes don’t cause visible UI changes for most customers. However, if you’ve used unsupported CSS overrides to customize an Experience Cloud site or Lightning pages, those customizations may lead to undesirable visual changes as we continue to update our architecture.

Internal Design System Architecture Updates Go Live in Summer 24

Frequently Asked Questions:

What is the Salesforce Lightning Design System?

Salesforce Lightning Design System (SLDS) is the design system and CSS framework that delivers the look and feel of Lightning Experience.

Why is Salesforce changing SLDS?

We’re modifying the design system architecture to support future product innovations. The changes we’re making in the Summer ’24 release won’t be visible to most customers.

How can the changes affect my Salesforce pages and sites?

If you’ve customized the visual design of your pages or sites by using supported techniques, our changes should have little to no impact on your customizations.
If you have used unsupported CSS overrides to customize an Experience Cloud site or Lightning pages, those customizations can lead to undesirable visual changes or regressions as we update our architecture.

Where is it documented that overriding CSS to customize Salesforce components is not supported?

See Salesforce Component Internals Are Protected.
For more information, see Anti-Patterns for Component Styling in the Lightning Web Components Developer Guide.
The Lightning Aura Components Developer Guide warns against depending on component internals in Base Lightning Components Considerations.

What are the supported techniques for customizing the styling in my Lightning components?

The supported techniques for customizing the styling of Lightning components differ depending on the model you use: Lightning Web Components (“LWC”) or Aura Components.
The supported techniques for LWC components are documented in these locations:
- Lightning Design System website: Styling Hooks
- Lightning Web Components Developer Guide: Style Components Using Lightning Design System Styling Hooks
The documented techniques for styling Aura components feature Aura design tokens. We recommend migrating your Aura components to LWC components and using styling hooks.
Alternatively, you can use styling hooks instead of Aura tokens in your Aura component’s CSS, using the same techniques used for LWC components. Design tokens are an older way of customizing components and are less likely to be resilient to any future changes than styling hooks.

What are the unsupported techniques that might cause visual regressions?

Experience Cloud sites and Lightning pages should avoid the following customizations. These customizations have the potential to cause visual regressions if they target components and styles that are changed in future releases.
- Overriding BEM style classes with deprecated syntax. After announcements in the release notes in Winter ’21 and Spring ’21, the BEM double-dash style classes were deprecated in Summer ’21. We’re planning to remove the double-dash style classes in a future release (safe harbor). For your custom components, we strongly encourage you to use the current BEM syntax that includes an underscore instead of a double-dash. If you’re overriding the CSS of Salesforce components, update the overrides to target both BEM class formats to ensure the overrides continue to work. For more information about BEM syntax in SLDS, see Markup and Style on the SLDS site.
- Targeting child DOM elements. Salesforce may at any point change the internal implementation of UI components. Starting in the Summer ’24 release, we’re changing the internals of some UI components, which can change the rendered DOM. You shouldn’t modify the DOM elements of Salesforce components via CSS or JavaScript or target SLDS classes in unit tests. See Salesforce Component Internals Are Protected. For more information, see Anti-Patterns for Component Styling in the Lightning Web Components Developer Guide.
- Overriding CSS of Salesforce components.
  - The Lightning Web Components Developer Guide cautions against overriding Salesforce components and their internals with your custom CSS in Anti-Patterns for Component Styling.
  - CSS overrides in Experience Cloud sites will continue to function as we move to styling hooks. However, sites that use overrides can’t adopt future product innovations of the UI without experiencing visual regressions.
- Use of unsupported –sds- styling hooks. Styling hooks were introduced as a beta feature in Winter ’21, using the –sds- namespace as described in the release note Customize Components with Lightning Design System Styling Hooks (Beta). In Spring ’22 styling hooks became generally available, with the namespace changed to –-slds- as described in the release note Customize Components with Lightning Design System Styling Hooks (Generally Available).
- Use of –lwc custom properties. In the Summer ’24 release, the –lwc custom properties still work in Lightning pages and Experience Cloud sites.
  - However, in Lightning pages, we strongly encourage you to replace –lwc custom properties during the Summer ’24 release with –slds styling hooks to avoid regressions when they’re removed in a future release.
  - In Experience Cloud LWR sites, when referencing –lwc custom properties, we strongly encourage you to replace them with –dxp, –slds-c, or –slds-g-color styling hooks. If you’re setting –lwc custom properties, you don’t need to take any action at this time. See –dxp Styling Hooks.

What visual regressions should I look for?

Visual regressions can range from a UI component displaying a slightly different color to layout changes in your UI.
The particular regressions that occur in your site or pages depend on your specific customizations. Areas where you might expect to see regressions in your customized sites or pages:
- Color
- Spacing
- Fonts
- Borders
- Layout
Developers or admins who are responsible for the customizations on Experience Cloud sites or Lightning pages must review the content during the Sandbox Preview starting May 10, 2024, before the Summer ‘24 release is live.

What should I do if my site or page has visual regressions?

Review your UI HTML and CSS for any of the unsupported customizations shown in the question, “What are the unsupported techniques that might cause visual regressions?”
If you find unsupported customizations, update the component code or CSS to use supported techniques.
See this document and follow the proposed solutions to update: Prepare Component Customizations for SLDS Architecture Updates.

Who can make the changes?

To replace the CSS overrides with styling hooks, you should have some knowledge of HTML, CSS, and Lightning Design System.

What resources do you have to help resolve the CSS overrides?

Prepare Component Customizations for SLDS Architecture Updates
New Global Styling Hook Guidance in the Lightning Design System

What if styling hooks are not available for the desired customization?

If the customization you’re making to the Salesforce component is a business requirement, you must create a custom component that implements the styling that you want. Use your custom component instead of the Salesforce component.

Where can I get help for updating my customizations?

If you have trouble, ask for help on one of these Trailblazer Community Groups:

Can I disable the SLDS architecture updates?

No, the SLDS architecture updates can’t be disabled.

What are the benefits of updating customizations?

For Lightning pages, if you customize components using –slds- styling hooks, your pages will:
- Continue to look and behave as you expect in the current release
- Be ready to adopt future product innovations, without additional changes to your code or CSS
For Experience Cloud sites, if you customize sites using recommended guidance, your site will:
- Continue to look and behave as you expect in the current release
- Show little to no change caused by updates to the UI architecture in coming releases, without additional changes to your customizations

What is the impact if I don’t update the customizations?

If you customize Lightning pages or Experience Cloud sites by targeting Salesforce components and CSS styles that are changing, you can potentially see some visual regressions.
The new UI architecture uses –slds styling hooks in place of SLDS design tokens and –lwc custom properties. If you have custom components using unsupported customization techniques, they will continue to display the current visual experience but won’t be able to cleanly adopt future product innovations.

How can I prepare Experience Cloud sites for the SLDS architecture updates?

CSS overrides in Experience Cloud sites will continue to function as we move to styling hooks in the SLDS architecture. You don’t need to update them.
Sites that use CSS overrides can’t adopt future product innovations of the UI without experiencing visual regressions.
When referencing –lwc custom properties, we strongly encourage you to replace them with –dxp, –slds-c, or –slds-g-color styling hooks. If you’re setting –lwc custom properties, you don’t need to take any action at this time. See –dxp Styling Hooks.