Skip to main content

Transition Your Org from SLDS 1 to SLDS 2

Learning Objectives

After completing this unit, you’ll be able to:

  • List the SLDS 2 transition tasks for developers.
  • List your admin’s and designer’s SLDS 2 transition tasks.
  • Discuss how to set up a test org, SLDS Linter, SLDS Validator, and SARIF Viewer to audit your design code.

Your SLDS 2 Transition

Uplifting your code from SLDS 1 to SLDS 2 is straightforward when you follow some simple steps. Depending on how many custom components you have, however, the uplift can be quick or it can take more effort. Either way, we’ve got a process and some helpful resources for you.

Note

Note: The transition from SLDS 1 to SLDS 2 and Salesforce Cosmos is a significantly lighter effort than the transition from Classic to Lightning.

A Salesforce developer moving round objects from a pile on the floor to a table.

As a developer, you’re responsible for assessing the deep technical details of your custom components and third-party apps for SLDS 2 capability and uplift. There are a handful of steps that you, your designer, and your admin must follow as a team.

Let’s start with the steps for your designer and admin.

Transition Tasks for Your Designer

Your designers are responsible for the consistent look and feel of your brand across your org. Here’s what your designers will do.

  • Validate the visual consistency across your UI.
  • Use Figma kits to update designs.
  • Support the testing of custom components for unexpected visual behavior.

Transition Tasks for Your Admin

Rely on your Salesforce admin to coordinate the overall uplift from SLDS 1 to SLDS 2 project. (More on your admin’s steps in the Go Live section.)

Transition Tasks for You: Assess Your Code and Uplift to SLDS 2

To assess your code and uplift it to SLDS 2, at a high level, you:

  1. Set up a development environment and assess your org’s readiness.
  2. Analyze your code using SLDS Linter or SLDS Validator, and our Figma kits.
  3. Update your component code to comply with SLDS 2 standards.
  4. Test your code in your development environment.
  5. Redeploy your code and launch the new version of your org.

Let’s get started.

Set Up Your Development Environment

You need an environment to test SLDS 2 in. Your test org must meet these minimum requirements.

  • Minimum Salesforce version: Winter '25
  • Supported browsers: Latest versions of Chrome, Firefox, Safari, and Edge
Note

Note: For more details about SLDS 2 availability and org requirements, read Salesforce Cosmos Theme and SLDS 2 Availability.

Create your scratch or sandbox org and configure it.

Depending on your org’s Salesforce product and edition, SLDS 2 and the Salesforce Cosmos theme might already be enabled. If it isn’t, follow these instructions.

  1. In your org, click Setup and select Setup.
  2. For Starter orgs, click Open Advanced Setup. For all other orgs, skip this step.
  3. In the Quick Find box, search for and select Themes and Branding.
  4. From the Salesforce Cosmos theme dropdown list, select Activate.
Note

Note: When you activate Salesforce Cosmos, SLDS 2 is also activated for your entire org.

Next, review your code for common features that might need special attention, like managed package components or Lightning Out (Beta) implementations. Use our Transition to SLDS 2 guide on the SLDS 2 website.

Analyze Your Code Using SLDS Linter

Your test environment is ready to go and you assessed your code. Next, use SLDS Linter and our Figma kits to audit your code, identify components to update to SLDS 2, and automatically fix your code. It's easy to set up, offers increased automation, and contains a robust library of rules reflecting the new SLDS 2 styling guidelines. We recommend that you use SLDS Linter.

Follow these instructions to audit your code.

To get started with SLDS Linter, complete these prerequisites:

Next, install and run SLDS Linter on your project. In VS Code, in your project root directory, follow these steps.

  1. Open a Terminal.
  2. To run SLDS Linter, run this command. 
npx @salesforce-ux/slds-linter@latest lint

If SLDS Linter isn’t installed, you’re asked to install the SLDS Linter package. Type ‘y’ to install the package.

  1. Review the linting output that’s displayed in the console. Notice how it includes the row and column numbers.
  2. Select the displayed numbers to go to specific lines in the source code (Command+Click on macOS).
  3. Run this command to produce a SARIF report in your project’s root directory.
npx @salesforce-ux/slds-linter report

The output file is named as slds-linter-report.sarif.

After you've generated the SARIF report, use VS Code's SARIF Viewer to see the results. Make a note of how many components SLDS Linter has identified for fixing.

To fix the errors that you identified with SLDS Linter, you have two options:

  • Fix issues automatically in bulk by running this command. 
        npx @salesforce-ux/slds-linter@latest lint --fix
  • Manually fix your code based on the recommendation that SLDS Linter provides.

After you fix the identified errors, run SLDS Linter to revalidate your code. 

	npx @salesforce-ux/slds-linter@latest lint

If there are no violations, you successfully uplifted your code to SLDS 2 standards. Fantastic!

For more detailed instructions on using SLDS Linter, refer to SLDS Linter. For more detailed information on updating and testing your code, read Transition to SLDS 2.

Analyze Your Code Using SLDS Validator

We recommend that you use SLDS Linter. However, you may use SLDS Validator and our Figma kits to audit your code and identify components to update to SLDS 2. Follow these instructions to audit your code with SLDS Validator.

Install and configure SLDS Validator with these steps.

  1. Install Visual Studio Code v.1.26 or later.
  2. Install the Salesforce Extension Pack.
Note

Note: After installation, all Salesforce extensions included in the pack should be automatically enabled, including SLDS Validator.

  1. Follow these instructions to set up JDK.

Now, in order to use the SLDS Validator bulk reporting functionality, you must install the SARIF Viewer extension.

  1. In Visual Studio (VS) Code, click Extensions (Shift-Cmd-X on MacOS or Ctrl+5 on Windows).
  2. Search for and select Sarif Viewer.
  3. Click Install.

Now you’re ready to validate your code.

  1. In VS Code, open the folder that contains your org’s component code that you want to validate.
  2. Open the VS Code Command Palette (Cmd-Shift-P on Mac OS, or Win+P on Windows).
  3. Type and select SLDS: Generate Sarif Report.
  4. For Select the folder(s) to perform the analysis, select Folder and Output Directory.
  5. Click OK.
  6. Open the generated SARIF file.

Once you've generated the SARIF report, use VS Code's SARIF Viewer to see the results. The report shows you instances of:

  • Component-level issues that must be addressed
  • CSS class violations
  • Instances of design tokens that should be updated to styling hooks
  • Accessibility concerns

For each identified issue, SLDS Validator indicates:

  • The location of the code requiring updates
  • A description of the problem
  • Recommended fixes
  • The priority level, for example, error or warning

For more detailed instructions on using SLDS Validator, refer to SLDS Validator for VS Code.

Update and Test Your Code

Here’s where your org’s transition from SLDS 1 to SLDS 2 gets real. Now, update any components that you identified in the previous phase to conform to the new design and recommendations that you learned through our tools.

At a high level, iteratively follow these instructions:

  1. Use SLDS Linter or SLDS Validator to review and accept recommendations.
  2. Refer to the Get Started: Developers guide for guidance on how to update the CSS within your components.
  3. Use our Figma Kit: Components for Web | Lightning Design System v2 and Figma Kit: Style Guide—SLDS Web Components v2 to support any new designs or customizations.
  4. Test your code using functional validation, visual regression testing, and, if applicable, testing across different customer environments.

For more detailed information on updating and testing your code, read Transition to SLDS 2.

Go Live

You just assessed your code and uplifted your custom components to SLDS 2. Double-check with your Salesforce admins and designers, then you’re ready to go live with SLDS 2.

Here are your go-live steps.

  1. Revalidate your updated code with SLDS Linter or SLDS Validator.
  2. Perform a visual regression test of your design. Your designer can help.
  3. Update your documentation and training materials. Your admin can help.
  4. Create and send out communications to your customers, such as release notes and blog posts. Reach out to your Salesforce admin for help.

We also encourage you to ​​provide post-release feedback to the Salesforce Design Systems team in our Design Trailblazers Group.

Onward and Upward

Whew! Time to celebrate. While SLDS 2 is intuitive, that’s a lot of information you just absorbed. Head on over to the next unit, where you learn about support resources and some of the most frequently asked questions.

Resources

Comparta sus comentarios de Trailhead en la Ayuda de Salesforce.

Nos encantaría saber más sobre su experiencia con Trailhead. Ahora puede acceder al nuevo formulario de comentarios en cualquier momento en el sitio de Ayuda de Salesforce.

Más información Continuar a Compartir comentarios