Lightning Design System
The Lightning Design System (SLDS) is Salesforce's open-source design system and CSS framework that gives Lightning Experience its look and feel.
Definition
The Lightning Design System (SLDS) is Salesforce's open-source design system and CSS framework that gives Lightning Experience its look and feel. It defines the visual language used across Lightning Experience, the Salesforce mobile app, Experience Cloud sites, and custom Lightning Web Components. SLDS bundles the styling hooks (colors, spacing, typography), the CSS utility classes, the component blueprints, and a public reference site at lightningdesignsystem.com that documents every pattern with markup examples.
SLDS is the layer that makes a custom component look like it belongs in Salesforce. A developer adds SLDS classes to component markup (slds-button, slds-card, slds-grid) and the element inherits the Salesforce identity automatically: the same colors, spacing, hover states, and accessibility behavior. Inside Lightning Experience the styles load with no import or static resource. The system is also published on GitHub, so non-Salesforce web apps can install it and share the same visual language. In Spring '25 Salesforce introduced SLDS 2, a new architecture that prioritizes CSS custom properties.
How SLDS shapes the Salesforce interface
What sits inside the design system
SLDS is more than a stylesheet. It is a packaged design system with four moving parts that work together. The first is the styling layer: colors, spacing scales, typography, border radii, and shadows, expressed today as CSS custom properties. The second is the CSS framework, a large set of utility and component classes you apply directly in markup. The third is the blueprint library, documented on lightningdesignsystem.com, which shows the correct HTML, classes, and states for each pattern. The fourth is the set of developer tools, including the SLDS Validator and the newer SLDS Linter, that check your code against current guidelines. Together these pieces let a team build interfaces that match Salesforce without reinventing buttons, cards, modals, or data tables. A developer who learns the system once can produce consistent screens across Lightning Experience, the mobile app, and Experience Cloud. That consistency is the whole point: users move between standard and custom pages without noticing a seam in the design.
Utility classes and component blueprints
Most day-to-day SLDS work happens through classes. Utility classes handle spacing and layout, like slds-m-around_medium for margin on all sides or slds-p-vertical_large for vertical padding. Layout helpers such as slds-grid and slds-col build responsive rows and columns. Component classes such as slds-button_brand or slds-card__header style a specific pattern. You rarely write these from memory. Instead you open the relevant blueprint on the SLDS reference site, copy the documented markup, and adjust the content. Each blueprint covers a single pattern: button, card, input, modal, data table, path, picklist, tabs, toast, and many more. The blueprint shows the markup, the classes, the visual states (default, hover, active, disabled), and the accessibility notes. Inside a Lightning Web Component you also have the option to compose from base lightning- components, which already wrap these blueprints. A lightning-button with variant="brand" renders the branded button without you touching a single SLDS class.
Design tokens, then styling hooks
Early SLDS exposed customization through design tokens, named values like the brand color or a spacing unit. In CSS you referenced them with the --lwc- prefix, for example --lwc-spacingSmall. Tokens still work in SLDS 1 themes, but they are not included in SLDS 2, and Salesforce now steers developers toward styling hooks instead. A styling hook is a placeholder in the SLDS stylesheet that you fill by declaring a matching CSS custom property in your own component. There are two kinds. Component styling hooks use the --slds-c- prefix and change one component without affecting others, such as a thicker border on a single button. Global styling hooks use the --slds-g- prefix and apply across the whole app, such as a brand color used everywhere. One detail trips people up: token and hook values are resolved at compile time, so runtime CSS calls like getPropertyValue do not read them. The practical guidance is to favor global color styling hooks, which also help your colors meet WCAG 2.1 contrast standards.
Accessibility comes with the blueprint
Accessibility is built into SLDS rather than bolted on later. Every component blueprint documents the ARIA roles and attributes, the keyboard navigation behavior, and the color contrast the pattern needs. A modal blueprint specifies focus trapping and the close behavior. A data table blueprint specifies header associations and row selection semantics. When you build a component straight from the blueprint, you inherit those behaviors for free, and the result tends to pass accessibility checks. The risk appears when you deviate. If you hand-roll a custom widget and skip the ARIA wiring, or override SLDS classes with your own CSS, you can quietly break the accessibility the blueprint provided. That is one more reason the documentation pushes you to start from the blueprint and to use styling hooks rather than overriding classes. SLDS 2 reinforces this by recommending global color hooks that align with WCAG 2.1 contrast, so brand customization and accessibility move in the same direction instead of fighting each other.
What changed in SLDS 2
SLDS 2 is a structural refresh, not a coat of paint. Salesforce introduced it in Spring '25 and built it on a CSS framework that separates structure from visual design using styling hooks. The default look changes too. SLDS 1 ships the familiar Lightning Blue theme, while SLDS 2 defaults to a theme called Salesforce Cosmos that an admin enables in org settings. Design tokens are dropped from SLDS 2, and global styling hooks become the supported way to customize. There is a transition gap worth knowing: component styling hooks (the --slds-c- ones) are not yet supported in SLDS 2, so components that depend on them stay on SLDS 1 for now while Salesforce closes that gap. Existing SLDS 1 components keep working, so the move is opt-in rather than forced. The reference site now presents SLDS 2 content, with SLDS 1 documentation preserved at v1.lightningdesignsystem.com. New builds are the natural place to adopt SLDS 2 first.
Tools that smooth the transition
Migrating CSS by hand is slow and easy to get wrong, so Salesforce ships tooling to find and fix the gaps. The SLDS Validator is an extension for VS Code that supports both SLDS 1 and SLDS 2. It adds syntax highlighting, code completion, and inline validation so you catch deprecated tokens and disallowed overrides as you type. The newer SLDS Linter is a code analysis tool aimed squarely at the SLDS 2 transition. It scans your code against current guidelines, flags design tokens and custom components that need updates, and offers automated fixes in bulk rather than one file at a time. The recommended path is straightforward. Run the tooling to locate design tokens in your code, replace them with global styling hooks that work in both SLDS 1 and SLDS 2, and prefer the semantic UI color hooks over the original color hooks. Doing the cleanup now means a custom component can adopt the Cosmos theme later without a scramble, and your styling stays valid as the design system keeps evolving.
Open-source reach beyond Salesforce
SLDS is published on GitHub under an open-source license, which extends its reach past the Salesforce platform. A non-Salesforce web application can install the SLDS package and reference the same classes in its markup, producing the Salesforce visual language on a surface that has nothing to do with the CRM. Teams use this for marketing sites, documentation portals, and internal tools that should feel like part of the same product family as their Salesforce org. The benefit is brand consistency across very different surfaces: a custom Lightning page inside Lightning Experience and a standalone website can share buttons, cards, and color that look identical. The reference site doubles as the public face of this distribution, documenting every blueprint so an external developer has the same guidance as a platform developer. Because Salesforce updates SLDS with each release, both audiences track the same evolving system. That shared cadence is what keeps the internal and external experiences from drifting apart over time.
Apply and customize SLDS in a Lightning Web Component
You do not install SLDS inside Lightning Experience; the styles are already there. The setup work is applying it correctly in a custom Lightning Web Component and customizing the brand through styling hooks rather than overriding classes. Here is the practical flow.
- Start from a blueprint
Open lightningdesignsystem.com, find the pattern you need (button, card, modal, data table), and copy the documented markup with its SLDS classes into your component template.
- Prefer base components
Where a base lightning- component exists, use it instead of raw classes. A lightning-button with variant="brand" gives you a branded, accessible button with no SLDS class wiring.
- Customize with styling hooks
To change appearance, declare a CSS custom property in your component's stylesheet. Use a --slds-c- hook on the :host selector for one component, or a --slds-g- global color hook for an app-wide brand color.
- Validate the code
Install the SLDS Validator in VS Code, then run the SLDS Linter to flag deprecated design tokens and class overrides. Apply its automated fixes and re-run until the code is clean.
Changes one component only, like a thicker border on a single button; not yet supported in SLDS 2 themes.
Sets a value used across the whole app, such as a brand color; works in both SLDS 1 and SLDS 2 and helps meet WCAG 2.1 contrast.
Wraps an SLDS blueprint with built-in styling and accessibility; the fastest way to stay consistent without classes.
- Do not override SLDS classes with your own CSS; overrides break when SLDS updates ship. Use styling hooks instead.
- Design tokens (the --lwc- variables) work in SLDS 1 but are absent from SLDS 2. Replace them with global styling hooks.
- Component styling hooks (--slds-c-) are not yet supported in SLDS 2, so components that rely on them stay on SLDS 1 for now.
- Token and hook values resolve at compile time, so runtime CSS APIs like getPropertyValue will not read them.
Prefer this walkthrough as its own page? How to Lightning Design System in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Lightning Design System.
- SLDS Styling Hooks (LWC Developer Guide)Salesforce
- SLDS Design Tokens (LWC Developer Guide)Salesforce
Hands-on resources to go deeper on Lightning Design System.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the Salesforce Lightning Design System (SLDS)?
Q2. What do SLDS design tokens provide as a layer between specific values and components?
Q3. What does the SLDS open-source distribution include for designers and front-end engineers?
Discussion
Loading discussion…