CSS style guide

This page documents conventions for our Launchpad CSS and SCSS files. Following the principles outlined in this document will minimize comments related to CSS conventions from reviewers.

Class Names

Overall, for naming a class we use lower case words separated by hyphens (-). For example:

# Good
<div class="social-accounts">...</div>

# Bad
<div class="social_accounts">...</div>
<div class="socialaccounts">...</div>
<div class="SocialAccounts">...</div>

When it comes to naming classes, for new components we follow the BEM convention, which is also used by the Vanilla framework.


When creating a new component or section with nested elements that have no standalone meaning, the nested elements should have the name of the parent block class, followed by two underscores (__), followed by the element name. For example:

# Good
<div class="social-accounts">
    <div class="social-accounts__item">...</div>

# Bad
<div class="social-accounts">
    <div class="social-accounts-item">...</div>
    <div class="item-social-account">...</div>

See Vanilla accordions as another example.

When it comes to modifiers for a class (classes to change appearance, behaviour or state), you should use the name of the original class, followed by two hyphens (--), followed by the modifier name. For example:

# Good
<div class="message">...</div>
<div class="message--error">...</div>
<div class="message--success">...</div>

# Bad
<div class="message error">...</div>
<div class="error-message">...</div>

See Vanilla buttons as another example.


In general, SCSS files are preferred over CSS files.

When adding CSS styling to a new block/section/component, one should create a new SCSS file in the lib/canonical/launchpad/icing/css/components directory named after the new component, and add it to the _index.scss file in the same directory.

Nesting class styles can be used when writing SCSS when it makes sense and as long as its nesting is kept to a level or two. For example:

.social-accounts {
    padding: 1em;
    color: grey;

    a {
        color: black;