Lightning Design System Considerations

Although the base Lightning components provide Salesforce Lightning Design System styling out-of-the-box, you may still want to write some CSS depending on your requirements.

If you're using the components outside of the Salesforce app and Lightning Experience, such as in standalone apps and Lightning Out, extend force:slds to apply Lightning Design System styling to your components. Here are several guidelines for using Lightning Design System in base components.

Using Utility Classes in Base Components

Lightning Design System utility classes are the fundamentals of your component's visual design and promote reusability, such as for alignments, grid, spacing, and typography. Most base components provide a class attribute, so you can add a utility class or custom class to the outer element of the components. For example, you can apply a spacing utility class to lightning:button.

1<lightning:button name="submit" label="Submit" class="slds-m-around_medium"/>

The class you add is appended to other base classes that are applied to the component, resulting in the following markup.

1<button class="slds-button slds-button_neutral slds-m-around_medium"    
2        type="button" name="submit">Submit</button>

Similarly, you can create a custom class and pass it into the class attribute.

1<lightning:badge label="My badge" class="myCustomClass"/>

You have the flexibility to customize the components at a granular level beyond the CSS scaffolding we provide. Let’s look at the lightning:card component, where you can create your own body markup. You can apply the slds-p-horizontal_small or slds-card__body_inner class in the body markup to add padding around the body.

1<!-- lightning:card example using slds-p-horizontal_small class -->
2<lightning:card>
3  <aura:set attribute="title">My Account</aura:set>
4  <aura:set attribute="footer">Footer</aura:set>
5  <aura:set attribute="actions">
6    <lightning:button label="New"/>
7  </aura:set>
8  <p class="slds-p-horizontal_small">
9    Card Body
10  </p>
11  </lightning:card>

1<!-- lightning:card example using slds-card__body_inner -->
2<lightning:card>
3    <aura:set attribute="title">My Account</aura:set>
4    <aura:set attribute="footer">Footer</aura:set>
5    <aura:set attribute="actions">
6      <lightning:button label="New"/>
7    </aura:set>
8    <div class="slds-card__body_inner">
9      Card Body
10    </div>
11</lightning:card>

Block-Element-Modifier (BEM) Notation

CSS class names used by Lightning base components match the Block-Element-Modifier (BEM) notation that Salesforce Lightning Design System uses. Class names that previously contained a double dash now use a single underscore in place of the double dash. A CSS class that used to be slds-p-around--small is now slds-p-around_small, for example. If you have created custom CSS in your components that reference an SLDS class that contains a double dash, update your selectors to use a single underscore. For more information, see Lightning Design System FAQ.

Applying Custom Component Styling

Sometimes the utility classes aren’t enough and you want to add custom styling in your component bundle. You saw earlier that you can create a custom class and pass it into the class attribute. We recommend that you create a class instead of targeting a class name you don’t own, since those classes might change anytime. For example, don’t try to target .slds-input or .lightningInput, as they are CSS classes that are available by default in base components. You can also consider using tokens to ensure that your design is consistent across your components. Specify values in the token bundle and reuse them in your components’ CSS resources.

Showing and Hiding with Styles

Lightning Design System utility classes include visibility classes that enable you to show and hide elements. These classes are designed as show/hide pairs that you add and remove, or toggle, with JavaScript. Apply only one class at a time. See Lightning Design System: Utilities: Visibility for descriptions of the classes. For information about using JavaScript to toggle markup see Dynamically Showing or Hiding Markup.

Using the Grid for Layout

lightning:layout is your answer to a flexible grid system. You can achieve a simple layout by enclosing lightning:layoutItem components within lightning:layout, which creates a div container with the slds-grid class. To apply additional Lightning Design System grid classes, specify any combination of the lightning:layout attributes. For example, specify vertical-align="stretch" to append the slds-grid_vertical-stretch class. You can apply Lightning Design System grid classes to the component using the horizontalAlign, verticalAlign, and pullToBoundary attributes. However, not all grid classes are available through these attributes. To provide additional grid classes, use the class attribute. The following grid classes can be added using the class attribute.

.slds-grid_frame
.slds-grid_vertical
.slds-grid_reverse
.slds-grid_vertical-reverse
.slds-grid_pull-padded-x-small
.slds-grid_pull-padded-xx-small
.slds-grid_pull-padded-xxx-small

This example adds the slds-grid_reverse class to the slds-grid class.

1<lightning:layout horizontalAlign="space" class="slds-grid_reverse">
2   <lightning:layoutItem padding="around-small">
3     <!-- more markup here -->
4   </lightning:layoutItem>
5   <!-- more lightning:layoutItem components here -->
6</lightning:layout>

For more information, see Grid utility.

Applying Variants to Base Components

Variants on a component refer to design variations for that component, enabling you to change the appearance of the component easily. While we try to match base component variants to their respective Lightning Design System variants, it’s not a one-to-one correspondence. Most base components provide a variant attribute. For example, lightning:button support many variants—base, neutral, brand, destructive, and inverse—to apply different text and background colors on the buttons.

1<lightning:button variant="brand" label="Brand" onclick="{! c.handleClick }" />

Notice the success variant is not supported. However, you can add the slds-button_success class to achieve the same result.

1<lightning:button name="submit" label="Submit" class="slds-button_success"/>

Let’s look at another example. You can create a group of related information using the lightning:tile component. Although this component doesn’t provide a variant attribute, you can achieve the Lightning Design System board variant by passing in the slds-tile_board class.

1<aura:component>
2  <ul class="slds-has-dividers_around-space">
3    <li class="slds-item">
4      <lightning:tile label="Anypoint Connectors" href="/path/to/somewhere" class="slds-tile_board">
5          <p class="slds-text-heading_medium">$500,000</p>
6          <p class="slds-truncate" title="Company One"><a href="#">Company One</a></p>
7          <p class="slds-truncate">Closing 9/30/2015</p>
8       </lightning:tile>
9    </li>
10  </ul>
11</aura:component>

If you don’t see a variant you need, check to see if you can pass in a Lightning Design System class to the base component before creating your own custom CSS class. Don’t be afraid to experiment with Lightning Design System classes and variants in base components. For more information, see Lightning Design System.

Lightning Components Developer Guide