How to use CSS and the Lightning Design System (SLDS)

When developing modern web applications, user interface design plays a crucial role in the overall user experience. Salesforce provides a powerful framework for building user interfaces using Lightning Web Components (LWC), and to help developers create clean, consistent, and accessible designs, Salesforce offers the Lightning Design System (LDS). Along with custom CSS, LDS provides the building blocks for creating Salesforce-like interfaces with minimal effort. In this blog post, we’ll explore how to use CSS in conjunction with the Lightning Design System (SLDS) to style your Lightning Web Components (LWC) and provide some best practices to ensure a great user experience.

What is the Lightning Design System (SLDS)?

The Lightning Design System (LDS) is Salesforce’s official front-end framework. It’s designed to help developers and designers create applications that are consistent with Salesforce’s look and feel. LDS provides:

• Pre-built UI components: Buttons, cards, modals, data tables, and more.
• Responsive grid system: For creating flexible and adaptive layouts.
• Utility classes: For spacing, typography, alignment, and other common styling needs.
• Accessibility features: Built-in support for ARIA roles, keyboard navigation, and screen reader compatibility.

LDS uses a Salesforce-specific design language, so any component you create with LDS will seamlessly integrate with the Salesforce platform, ensuring a smooth user experience.

Why Use Custom CSS with LDS?

While LDS is incredibly powerful, there are times when you’ll need to go beyond its capabilities. Here are some scenarios where custom CSS comes into play:

1. Branding Customization: Tailoring components to match your organization’s unique brand identity (e.g., custom colors, fonts, or logos).

2. Unique Layouts: Creating complex designs that aren’t covered by LDS’s grid or utility classes.

3. Interactive Effects: Adding animations, hover states, transitions, or other dynamic effects.

4. Overriding Defaults: Making minor adjustments to LDS components for specific use cases.

However, it’s important to use custom CSS judiciously. Overriding LDS styles too heavily can lead to maintenance challenges and potential conflicts during updates.

Integrating LDS with Lightning Web Components (LWC)

Example 1. Using LDS in LWC: Base Components

One of the simplest ways to use the Lightning Design System in LWC is by leveraging Salesforce’s base components. These are pre-built UI components that are styled using LDS.

For example, consider the following basic example of using an LDS button: 

 <template>
    <lightning-button label="Click Me" onclick={handleClick}></lightning-button>
</template>

Here, <lightning-button> is a base LWC component that automatically uses LDS styling, so you don’t need to write any custom CSS for the button to look like a native Salesforce button. You simply use the component and it adheres to the design system. 

Other commonly used base components include:

• <lightning-input>
• <lightning-card>
• <lightning-layout>
• <lightning-icon> 

These components automatically apply the relevant LDS styles, ensuring that your application looks consistent with Salesforce’s UI guidelines.

2. Custom Styling with CSS in LWC

While LDS provides many pre-styled components, you can still add custom styles to your components in LWC using traditional CSS. In LWC, each component has its own shadow DOM, which means that styles you apply will be scoped to that component. This encapsulation ensures that your custom styles don’t leak out and affect other components on the page.

How to add custom CSS:

1. Create a CSS file in your component’s directory.
   The file must be named yourComponentName.css to be automatically associated with the component.
2. Use the standard CSS syntax to style your component.

For example, you can create a custom button component with additional CSS styling:

<template>
    <lightning-card title="Button Example">
        <button class="custom-button" onclick={handleClick}>Custom Button</button>
    </lightning-card>
</template>

CSS

.custom-button {
    background-color: #0070d2;
    color: white;
    border: 1px solid #005bb5;
    padding: 10px 20px;
    border-radius: 5px;
    font-size: 16px;
    cursor: pointer;
}

.custom-button:hover {
    background-color: #005bb5;
}

Javascript:

import { LightningElement } from 'lwc';

export default class CustomButton extends LightningElement {
    handleClick() {
        alert('Button clicked!');
    }
}

The custom button now uses a unique background-color and other styles, while maintaining its own scoped styling thanks to the shadow DOM.

3. Leveraging LDS Utility Classes

Salesforce’s Lightning Design System provides several utility classes that can be used in your LWC to quickly style elements without writing custom CSS. These utility classes are designed to manage layout, spacing, typography, colors, and more.

Example using LDS utility classes:

<template>
        <lightning-card title="Button Example">
            <div class="slds-p-around_medium">
                <lightning-button class="slds-m-top_medium" label="Submit" onclick={handleClick}></lightning-button>
            </div>
        </lightning-card>
    </template>

In this example:

• slds-p-around_medium: Adds medium padding around the container.
• slds-m-top_medium: Adds a medium margin to the top of the button.

These utility classes allow you to quickly implement consistent styling in your components without needing to write custom CSS.

Common LDS utility classes include:

• slds-m-around_small, slds-p-top_large (margin and padding classes).
• slds-text-align_center, slds-text-color_error (text alignment and color).
• slds-size_1-of-2, slds-grid (layout and grid utilities).

These utilities can be mixed with custom CSS to create flexible and responsive designs.

Example 2: A Custom Input with LDS Styling and Custom Border Radius

In this example, we’ll use the lightning-input base component for a text input field, add custom styles for a rounded border, and apply an LDS utility class for margin and padding.

HTML 

<template>
    <lightning-card>
        <lightning-input label="Enter Your Name" value={name} onchange={handleChange} class="custom-input">
        </lightning-input>
    </lightning-card>

</template>

CSS

.custom-input {
    border-radius: 15px; /* Custom border radius for the input field */
    border: 2px solid #d25400; /* Custom blue border color */
}

.slds-m-bottom_medium {
    margin-bottom: 1rem; /* Add margin below the input field */
} 

Javascript

import { LightningElement } from 'lwc';

export default class CustomInput extends LightningElement {
    name = '';

    handleChange(event) {
        this.name = event.target.value;
    }
}

Explanation:

• The lightning-input component is used to create a text input field.
• We apply a custom border radius and color to the input element using the input selector inside .custom-input.
• LDS utility class slds-m-bottom_medium adds margin below the input field

Example 3: Custom Table with LDS Styles and Custom Header Row

Here we use the lightning-datatable base component to display data in a table format with custom styles for the header row.

HTML

<template>
    <lightning-datatable
        data={data}
        columns={columns}
        key-field="id"
        class="custom-table"
    ></lightning-datatable>
</template>

JavaScript

import { LightningElement } from 'lwc';

export default class CustomTable extends LightningElement {
    data = [
        { id: 1, name: 'John Doe', age: 25 },
        { id: 2, name: 'Jane Smith', age: 30 },
        { id: 3, name: 'Sam Wilson', age: 27 },
    ];

    columns = [
        { label: 'Name', fieldName: 'name' },
        { label: 'Age', fieldName: 'age' }
    ];
}

CSS

.custom-table  {
    color: #b58500;
    font-weight: bold;
}

Explanation:

• We use the lightning-datatable component to create a table with dynamic data.
• Custom CSS is applied to the header row to give it a distinct background and text color.
• We also use hover effects on table rows to improve the user experience

Best Practices for Combining CSS and LDS

1. Use LDS First

Always begin by leveraging LDS classes and components. For example, use slds-button for buttons or slds-card for cards before writing custom styles. This ensures consistency and accessibility.

2. Scope Your Styles

Avoid global CSS overrides, as they can lead to unintended side effects. Instead, use scoped CSS (e.g., in Salesforce Lightning Web Components) to limit your styles to specific components.

3. Leverage CSS Variables

LDS provides CSS custom properties (variables) for theming. Override these variables instead of hardcoding values to maintain consistency and simplify updates:

:host {
  --slds-c-button-brand-color-background: #FF6B6B;
  --slds-c-button-brand-color-border: #FF6B6B;
}

4. Combine Utility Classes

LDS offers a wide range of utility classes for quick styling. Chain these classes to achieve the desired look without writing custom CSS:

<div class="slds-p-around_medium slds-border_bottom slds-text-heading_small">
  Hello, World!
</div>

Conclusion

Combining CSS with the Lightning Design System (LDS) in Lightning Web Components (LWC) gives you the power to create beautiful, responsive, and consistent Salesforce applications while keeping things secure and standardized. By leveraging LDS’s pre-built components and utility classes alongside your own custom styling, you can focus on building rich user interfaces without sacrificing design consistency or performance.

With LDS, you not only ensure a uniform look across Salesforce but also improve the usability and accessibility of your components, making your application easier to navigate for all users. Learn about LDS2.