What Developers Can Learn from Data Cloud’s Large-Scale Uplift to SLDS 2
You, too, can resolve technical debt by using SLDS Linter to fix errors in bulk and by converting hard-coded CSS to styling hooks.
Salesforce’s products are powered by millions of lines of code, packaged up and organized into components and services designed to work reliably at the highest scale. Our design system — one of the first of its kind in enterprise software — was built to match this scale, enabling our internal teams to move quickly to deliver customer value without sacrificing consistency or accessibility.
But what happens when the design system itself needs an update across thousands of custom components and you have limited resources and time to address it? This was a real situation we faced, and a small team of Data Cloud engineers and user experience (UX) designers answered the call.
We transitioned the user interface (UI) to the new SLDS 2 styling hook architecture – and did everything in a single release. Here’s what we learned during the process and the insights you can apply to your SLDS 2 transition.
What we did
Use SLDS Linter to resolve issues at scale
Build confidence through low-risk changes
Resolve technical debt ‘on a shoestring’
Use SLDS Linter to resolve issues at scale
In Salesforce-on-Salesforce fashion, we followed our own Transition to SLDS 2 guide and adapted it for our internal practices. That might sound straightforward, but the task was daunting at Data Cloud’s scale. We had thousands of custom components, all working together in different ways to support critical customer flows – many of which were built by different teams with unique approaches to CSS customization.
It could take over a year to manually refactor thousands of components with only two dedicated engineering resources, so getting familiar with tooling and automation was critical.
We used, tested, and iterated with SLDS Linter to address most of the issues. Especially helpful were the SARIF report and the bulk-fix features. These gave us categorized overviews of error types and enabled us to resolve high-confidence errors automatically. Gaining this understanding of the proposed changes and running the fixes informed how we tackled subsequent sets of components.
As SLDS Linter made our process more reliable and scalable, we:
- Wrote scripts to further automate the linting process,
- created team-based git branches,
- updated testing snapshots,
- and used AI-powered summaries to give engineering teams an overview of the changes, providing them with context for further testing and approval.
Once the tooling and automation were in place, the prospect of uplifting Data Cloud to SLDS 2 was no longer as daunting. So we set a goal of completing the work within a three-month release cycle.
Build confidence through low-risk changes
We needed to demonstrate to our cloud engineering teams that they could trust the effectiveness of the developer tools at scale. They also needed to have confidence in the code that we’d be submitting to them. While our aim was to accelerate internal SLDS 2 adoption, we didn’t want it to be at the cost of customer trust.
Luckily, the scope of impact from SLDS 2 adoption is specific, and we can minimize the risk. Most of the critical changes take place in CSS files, and changes to existing values are preserved as fallbacks. The four areas we focused on included:
1. Convert to styling hooks
For example, we might see a custom CSS class in one of our Lightning Web Components with a hard-coded value.
.myCustomClass {
background: #FFF;
}CSS styling hooks aren’t new, but they have been updated for SLDS 2. Converting hard-coded CSS values to styling hooks is a critical practice to adopt for upcoming feature support.
.myCustomClass {
background: var(--slds-g-color-surface-1, #FFF);
}2. Update deprecated values
We also looked for any deprecated values, such as LWC or Aura tokens, and updated any deprecated semantics used in utility classes.
3. Mitigate CSS values that don’t have styling hooks yet
There aren’t enough styling hooks yet to cover all possible values. Where the old and new CSS values are the same, there’s no discernible difference in the user experience. However, there may be certain numeric color values that don’t render as expected. When we encountered those instances, we proposed solutions to our partners in UX, engineering, and product management. And we made sure to include clear explanations about the benefits.
4. Communicate early and often
We not only had a path to confidence in our proposed code, we also ensured teams understood what made these changes low-risk. As teams found success and shared their experiences, subsequent collaborations became easier.
The adoption of SLDS 2 picked up pace until we’d addressed nearly 3,000 lines of targeted code. By replacing custom CSS rules with existing utility classes, we also removed thousands of lines of redundant CSS code.
Resolve technical debt ‘on a shoestring’
Refactoring code is rarely the most exciting project on anyone’s to-do list. Given the scope and complexity of how components are managed, we weren’t sure we could accomplish our goal without overcommitting ourselves. Ultimately, we’re glad we made the uplift to SLDS 2 a priority.
We future-proofed Data Cloud and resolved years of technical debt with minimal resources. Data Cloud’s leaner, modernized components are now ready for SLDS 2 features like dark mode – powered by styling hooks – and a range of dynamic, personalized experiences coming in future releases.
Through this process, our engineering partners learned more about user interface composition, CSS customization, and validation tooling. This is important knowledge that raises their standards for how they build custom components in the future.
Importantly, by modeling how to manage such a massive transition to SLDS 2, we inspired other teams to make the move. We’re glad we didn’t wait and neither should you.
Build faster, future-proof your org
You can customize Salesforce with a flexible UI framework, advanced theming options, and robust tools for designers and developers. SLDS 2 paves the way to dark mode and sets the foundation for future agentic capabilities.
