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 Salesforce1 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.

<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.
<button class="slds-button slds-button--neutral slds-m-around--medium"    
        type="button" name="submit">Submit</button>
Similarly, you can create a custom class and pass it into the class attribute.
<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.

<!-- lightning:card example using slds-p-horizontal--small class -->
<lightning:card>
  <aura:set attribute="title">My Account</aura:set>
  <aura:set attribute="footer">Footer</aura:set>
  <aura:set attribute="actions">
    <lightning:button label="New"/>
  </aura:set>
  <p class="slds-p-horizontal--small">
    Card Body
  </p>
  </lightning:card>
<!-- lightning:card example using slds-card__body--inner -->
<lightning:card>
    <aura:set attribute="title">My Account</aura:set>
    <aura:set attribute="footer">Footer</aura:set>
    <aura:set attribute="actions">
      <lightning:button label="New"/>
    </aura:set>
    <div class="slds-card__body--inner">
      Card Body
    </div>
</lightning:card>  

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.

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.
<lightning:layout horizontalAlign="space" class="slds-grid--reverse">
   <lightning:layoutItem padding="around-small">
     <!-- more markup here -->
   </lightning:layoutItem>
   <!-- more lightning:layoutItem components here -->
</lightning:layout>
For more information, see lightning:layout and the 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.

<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.

<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.
<aura:component>
  <ul class="slds-has-dividers--around-space">
    <li class="slds-item">
      <lightning:tile label="Anypoint Connectors" href="/path/to/somewhere" class="slds-tile--board">
          <p class="slds-text-heading--medium">$500,000</p>
          <p class="slds-truncate" title="Company One"><a href="#">Company One</a></p>
          <p class="slds-truncate">Closing 9/30/2015</p>
       </lightning:tile>
    </li>
  </ul>
</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.