How Do You Migrate Salesforce LWC Components from SLDS 1 to SLDS 2 Without Breaking Styles?

The Problem: Your Salesforce UI Looks Broken After an Upgrade

You've just updated your Salesforce org or started a new project, and suddenly your carefully crafted Lightning Web Components (LWC) look different. Buttons have the wrong colors, spacing is inconsistent, and typography doesn't match the design system. You check the console and see warnings about deprecated tokens, hardcoded values, and class overrides. This is a common scenario when Salesforce updates its design system from SLDS 1 to SLDS 2, and your existing components haven't been migrated.

The core issue is that SLDS 2 introduces a new system of styling hooks—CSS custom properties that replace hardcoded values and deprecated tokens. If your components still use old patterns like --lwc-colorBackground, t(fontSizeMedium), or override SLDS classes directly, they won't adapt correctly to SLDS 2's theming, accessibility features, and density settings. Manual migration is tedious and error-prone: you have to identify every violation, choose the right replacement hook from hundreds of options, and ensure fallback values are preserved for backward compatibility.

This isn't just a cosmetic problem. Broken styles can affect user experience, accessibility compliance, and even functionality if layout shifts occur. For teams maintaining large Salesforce applications with hundreds of components, a systematic approach is essential to avoid regression bugs and ensure consistency across the UI.

What a Good Solution Should Change

A proper migration tool or skill should do more than just find problems—it should help fix them efficiently. Here's what you'd want from a solution:

• Automated detection: Scan all CSS and markup files to identify violations against SLDS 2 standards.
• Guided fixes: Provide clear, context-aware recommendations for each violation type, not just generic suggestions.
• Preserve functionality: Ensure that migrated components look and behave the same as before, with proper fallback values.
• Support all hook categories: Handle color, spacing, sizing, typography, borders, radius, and shadows—not just one or two.
• Integrate into workflow: Work with your existing development setup, whether you're using VS Code, CI/CD pipelines, or command-line tools.

The goal is to reduce the manual effort from days to hours, minimize the risk of introducing new bugs, and give developers confidence that their components are SLDS 2 compliant.

Introducing the SLDS 2 Migration Skill

One practical option to inspect is the design-systems-slds2-migrate skill. This skill is designed specifically for migrating LWC components from SLDS 1 to SLDS 2 by leveraging the official SLDS linter and providing structured guidance for fixing violations.

It's not a magic wand that automatically rewrites your code. Instead, it offers a systematic workflow: run the linter, analyze violations, apply fixes by category, choose the right hooks, and validate the results. The skill covers all styling hook categories and includes reference guides for each violation type, helping developers make informed decisions rather than guessing.

How the Skill Works: A Step-by-Step Overview

The skill follows a clear, repeatable workflow. Here's a simplified breakdown:

Step 1: Run the SLDS Linter

The first step is mandatory: run the SLDS linter on your component files. This tool analyzes .html and .css files, auto-fixes simple violations, and reports issues that need manual attention.

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

The linter output will show warnings and errors with specific line numbers and rule names, such as slds/no-hardcoded-values-slds2 or slds/lwc-token-to-slds-hook.

Step 2: Analyze Violations by Type

The linter categorizes violations into four main types:

1. Hardcoded values: Static CSS values like #ffffff or 16px that should use SLDS hooks.
2. Deprecated tokens: Old --lwc-* tokens or t() syntax that need replacement.
3. Class overrides: Direct overrides of .slds-* classes in your CSS.
4. Token migrations: Legacy token usage that requires hook replacement with fallbacks.

Each type has a different fix approach. For example, hardcoded values need to be replaced with a hook plus the original value as a fallback: var(--slds-g-color-surface-1, #ffffff).

Step 3: Fix Violations with Context-Aware Guidance

This is where the skill adds value. Instead of leaving you to guess which hook to use, it provides reference guides for each rule. For color hooks—which require the most judgment—it includes a decision guide based on the CSS property and context. For non-color hooks like spacing or typography, it offers lookup tables that map values to numbered scales.

A common pitfall is choosing the first hook suggestion from the linter output. The skill emphasizes that you must read the color hooks decision guide first, as the correct hook depends on whether you're setting a background, text, or border color.

Step 4: Handle Class Overrides Carefully

Overriding SLDS classes is a frequent issue. The skill explains that you need to change both CSS and markup:

• In CSS, rename the selector from .slds-button to a component-prefixed class like .myComponent-button.
• In HTML, add the new class alongside the original SLDS class—never remove the SLDS class.

This ensures your custom styles don't interfere with SLDS updates and maintain accessibility.

Step 5: Validate and Iterate

After making fixes, re-run the linter until you get zero errors. The skill includes a validation checklist to ensure all hooks have fallback values, no deprecated tokens remain, and components render correctly in different themes and density settings.

When to Consider This Skill

This skill might be worth inspecting if:

• You're maintaining Salesforce LWC components that use SLDS 1 styling patterns.
• You've encountered linter warnings about deprecated tokens or hardcoded values.
• Your team is planning an SLDS 2 uplift and wants a structured approach.
• You need to ensure consistency across a large codebase with many components.

It's particularly useful for frontend developers or Salesforce admins who are comfortable with CSS and command-line tools but want to avoid the tedious manual work of identifying and fixing each violation.

Capability Boundaries and Best Use Cases

The skill focuses specifically on SLDS 1 to SLDS 2 migration for LWC components. It doesn't cover:

• Aura component migration (though it can analyze .cmp files, the guidance is LWC-centric).
• JavaScript logic changes unrelated to styling.
• Custom design systems outside of SLDS.

Best use cases include:

• Incremental migration: Migrating components one by one as part of ongoing development.
• Codebase audits: Identifying all SLDS 1 violations before a major release.
• Team onboarding: Helping new developers understand SLDS 2 patterns and avoid common mistakes.

When Not to Use It

You might not need this skill if:

• Your components are already fully SLDS 2 compliant.
• You're using a different design system or custom CSS framework.
• You prefer to handle migration manually without tooling assistance.
• Your project doesn't use Lightning Web Components.

Setup Context and Safety Signals

The skill requires:

• Node.js 14.x or higher.
• Access to your component files (CSS and markup).
• A terminal to run the linter.
• A Git repository for backup (recommended to track changes).

From a safety perspective, the skill uses the official Salesforce SLDS linter, which is a trusted tool. The migration process preserves original values as fallbacks, reducing the risk of breaking changes. However, always test components thoroughly after migration, especially in different themes and accessibility modes.

Repository Signals

The skill is part of the sf-skills repository by forcedotcom, which has 780 stars and 285 forks. It's licensed under Apache-2.0, indicating it's open for use and modification. The repository appears actively maintained, with topics related to Salesforce development.

Final Thoughts

Migrating from SLDS 1 to SLDS 2 is a necessary step for keeping your Salesforce UI modern and accessible. While it involves careful work, tools like the design-systems-slds2-migrate skill can provide structure and reduce the burden. The key is to approach it systematically: run the linter, fix violations by category, choose hooks wisely, and validate thoroughly. Always back up your code and test in a sandbox before applying changes to production.