Skip to main content

Modify Custom Components for Dark Mode with SLDS Linter

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

  • Explain how to use SLDS Linter to validate custom component compliance with SLDS 2 dark mode styling.
  • Create a Salesforce DX project and edit custom component code.
  • Activate a custom theme in your org.
  • Activate the dark mode display setting in your org for your users.
  • Turn dark mode on in your org.

Now you know how dark mode transforms your Salesforce interface. Next, explore how you, as a developer, can make your custom components shine in dark mode. As you know, dark mode is built with the Salesforce Lightning Design System 2 (SLDS 2) styling hook architecture. This architecture is designed to integrate seamlessly with your custom developments while preserving your brand's unique identity. Get ready to make your custom components truly adaptable to light or dark modes.

Note

To complete the hands-on challenge in this badge, you must work in the custom Developer Edition org that you created in Unit 1.

Fix a Bug in Dark Mode

Remember that bug that you found in your dark mode preview? It’s time to squash that bug.

For the next steps and the remainder of this unit, you work with the Hello, World! app and its custom component code. Lucky for you, we already installed the app in your special Developer Edition org.

To start solving this problem by editing custom component code, here are the overall steps you take in this unit.

  1. Install some prerequisites.
  2. Work with SLDS Linter. It’s an awesome, free code analysis tool that analyzes your code and identifies SLDS 2 code discrepancies.
  3. Create a Salesforce DX (SFDX) project. SFDX is a set of tools designed to streamline the development and management of your Salesforce apps.
  4. Deploy your edited code back to your special Developer Edition org.

Let’s get started!

Note

If you’re completing this badge at Dreamforce ’25 in the Camp Design Agentblazer Forest, the prerequisite steps are already completed for you. Jump ahead to Authorize Your Developer Edition Org and Open Your Project and complete the remainder of the steps.

Salesforce DX and SLDS Linter Prerequisites

To get started with SFDX and SLDS Linter, complete these prerequisites:

You can learn more about SLDS Linter in the SLDS Linter Developer Guide and about SFDX in the Salesforce DX Developer Guide.

Create a Salesforce DX Project

Now that you set up your development environment, create a simple Lightning web component.

  1. In VS Code, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).
  2. Type and select SFDX: Create Project.
  3. Press Enter to accept the standard option.
  4. Enter HelloWorldLightningWebComponent as the project name.
  5. Press Enter.
  6. Select a root folder to store your project.
  7. Click Create Project.

Authorize Your Developer Edition Org and Open Your Project

With the VS Code Command Palette open, complete these steps to authorize your Developer Edition org.

  1. Type and select SFDX: Authorize an Org.
  2. Press Enter to accept the Project Default login URL option.
  3. Press Enter to accept the default alias. This opens the Salesforce login in a separate browser window.
  4. Log in using your Developer Edition org credentials.
  5. If prompted to allow access, click Allow.
  6. Return to VS Code.
  7. Click Terminal then select New Terminal.
  8. To pull down the already deployed helloWorld component to the /force-app/main/default/lwc folder, run this command:
    sf project retrieve start -m LightningComponentBundle:helloWorld
  9. To open the helloWorld component folder, run this command:
    cd force-app/main/default/lwc/helloWorld
  10. In VS Code Explorer, navigate to and open the helloWorld.css and helloWorld.html files.

An example view of VS Code Explorer with the helloWorld.css file open.

Use SLDS Linter to Validate Your Component Code

Now that you have your project’s component folder open, take a look at your code. It contains multiple SLDS components. Double-check that those components are SLDS 2 and dark mode-ready. 

HTML:
<template>
  <div class="my-custom-card slds-p-around--medium">
    <p>Hello, {greeting}!</p>
    <!-- Base Components ship with SLDS 2 support -->
    <lightning-input label="Name" value={greeting} onchange={changeHandler}></lightning-input>
  </div>
</template>


CSS:
.my-custom-card {
    background: var(--lwc-colorBackgroundAlt);
    color: rgb(92, 92, 92);
}

SLDS Linter helps developers verify that code complies with SLDS 2 standards and best practices, including dark mode styling. This proactive issue identification is crucial for future dark mode features, to aim for 100% design consistency, and to meet WCAG color contrast guidelines. SLDs Linter helps you maintain a consistent, accessible, high-quality user experience for your dark mode-ready components.

Run SLDS Linter

To identify code issues with your components, run SLDS Linter on your project. In VS Code, in your project root directory, follow these steps.

  1. Open Terminal.
  2. To run SLDS Linter on your helloWorld component folder, run this command: 
npx @salesforce-ux/slds-linter@latest lint
  1. If you’re asked to install packages, type y.

Review the linting output that’s displayed in the console. Notice how it includes the row and column numbers. And notice how the helloWorld component shows two violations, one in the CSS file and one in the HTML file. No worries—you can fix that.

An example SLDS Linter violation report showing one error and one warning in helloWord.css and one error in helloWorld.html.

Uplift a Custom Component to SLDS 2

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

  • Apply automatic fixes suggested by SLDS Linter.
  • Manually fix your code.

First, see what can be fixed automatically by using the --fix argument. This command fixes HTML and CSS files in your project folder. Next, fix a couple of bugs manually.

Complete these steps in your open Terminal:

  1. Run npx @salesforce-ux/slds-linter@latest lint --fix

An updated example SLDS Linter violation report now shows one warning and one error in helloWorld.css.

  1. View the output.
    Fantastic, you just fixed the HTML file. Notice that the remaining issues have recommendations in the output.
  1. Review your CSS file code and determine how to update it. If you need help, review this code, then copy and paste this SLDS 2 and dark-mode-compliant code into your CSS file: 
.my-custom-card {
    background: var(--slds-g-color-surface-container-1, var(--lwc-colorBackgroundAlt));
    color: var(--slds-g-color-on-surface-1);
}

So why is this updated code SLDS 2 and dark mode compliant?

  • The global styling hook pulls the corresponding light or dark value for the background color instead of static value provided by the --lwc-colorBackgroundAlt styling hook.
  • The text color correctly contrasts with the background color.
  1. Save your changes.
  2. Rerun SLDS Linter to re-validate your code. 
	npx @salesforce-ux/slds-linter@latest lint

Example SLDS Linter output showing no errors and no warnings.

Wow! No violations. You uplifted the component to SLDS 2 standards, fantastic.

Deploy Your Edited Code to Your Org

Now that you validated your custom components using SLDS Linter, you're ready to deploy your edited code to your Salesforce org.

In VS Code, complete these steps.

  1. Right click on the /force-app/main/default/lwc folder.
  2. Select SFDC: Deploy this Source to the Org.

An example options menu in VS Code with a highlight on SFDX: Deploy This Source to Org

  1. Wait for the deployment to complete.
  2. In your web browser with your org and the Hello, World! app open, refresh the page to see your updates.

An example Trailhead app Home page with the Hello, World! App and a Name field with the word World in the textbox.

Well, check that out. Your Hello, World! App now displays correctly in dark mode: the background is dark, and the font is light. Well done!

Activate Your Custom Theme and Dark Mode

You previewed dark mode and fixed a bug. You’re happy with what you see. You’re ready to activate the dark mode option for all your users. After dark mode is activated, each user can decide whether to turn it on or off in their personal view.

Follow these steps in your special Developer Edition org in Themes and Branding to activate dark mode.

  1. If you don’t have your custom theme (My Theme) open yet, from the dropdown next to My Theme, select Edit.
  2. Click Activate.

Congrats! You activated your custom theme and you activated dark mode at the org level for your users.

Turn Dark Mode On

Now that dark mode is activated at the org level, see how your users can enable it—or turn it on—for themselves. Yes, from Trish in Accounting to Pedro in Sales to Salome in Engineering, anyone can turn dark mode on and off. It’s super simple.

You enabled dark mode earlier in this module as one of the steps to preview your new theme. Here are the steps for your users to turn on dark mode. To try them out in your special Developer Edition org, from the App Picker, select the Trailhead app.

  1. Click your avatar to view your profile.
  2. In Color Mode (Beta), click dark.

That's it! Dark mode is now turned on in your personal org view. To turn off dark mode, if your computer's system setting is set to Light mode, simply repeat these steps and select Light or System. Keep in mind that if you switch from an SLDS 2 theme to an SLDS 1 theme, dark mode is automatically deactivated.

Wrap It Up

An AI-generated image of three employees with a nighttime sky and bright, full moon behind them.

You’ve come a long way! You:

  • Explored how dark mode integrates with custom components in Salesforce.
  • Worked through the recommended dark mode development flow.
  • Used powerful SLDS 2 styling hooks.
  • Validated your code with SLDS Linter.
  • Activated and enabled dark mode in your org.

By using these ideas, your custom solutions look great and provide a simple and consistent experience for all users, no matter what color mode they choose. Keep experimenting, and enjoy the power of adaptable design!

Now, make sure you complete all the steps in this unit in your special Developer Edition org, and then click Check Challenge to Earn 500 Points.

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