Skip to content

CSS Naming Conventions

Jump to bottom
0xadada edited this page Feb 8, 2017 · 2 revisions

Mir uses SUIT CSS naming conventions, with a few additions to address SCSS.

SUIT CSS naming conventions

SUIT CSS relies on structured class names and meaningful hyphens (i.e., not using hyphens merely to separate words). This helps to work around the current limits of applying CSS to the DOM (i.e., the lack of style encapsulation), and to better communicate the relationships between classes.

The primary architectural division is between utilities and components.

Table of contents

Utilities

Low-level structural and positional traits. Utilities can be applied directly to any element within a component.

Syntax: u-[sm-|md-|lg-]<utilityName>

u-utilityName

Utilities must use a camel case name. What follows is an example of how various utilities can be used to create a simple structure within a component.

<div class="u-cf">
  <a class="u-floatLeft" href="{{url}}">
    <img class="u-block" src="{{src}}" alt="">
  </a>
  <p class="u-sizeFill u-textBreak">
    …
  </p>
</div>

Responsive utilities

Certain utilities have responsive variants using the patterns: u-sm-<name>, u-md-<name>, and u-lg-<name> for small, medium, and large Media Query breakpoints.

Components

The CSS responsible for component-specific styling.

Syntax: [<namespace>-]<ComponentName>[-descendentName][--modifierName]

This has several benefits when reading and writing HTML and CSS:

  • It helps to distinguish between the classes for the root of the component, descendent elements, and modifications.
  • It keeps the specificity of selectors low.
  • It helps to decouple presentation semantics from document semantics.

namespace (optional)

If necessary, components can be prefixed with a namespace. For example, you may wish to avoid the potential for collisions between libraries and your custom components by prefixing all your components with a namespace.

.twt-Button { /* … */ }
.twt-Tabs { /* … */ }

This makes it clear, when reading the HTML, which components are part of your library.

ComponentName

The component's name must be written in pascal case. Nothing else in the HTML/CSS uses pascal case.

.MyComponent { /* … */ }
<article class="MyComponent">
  …
</article>

ComponentName--modifierName

A component modifier is a class that modifies the presentation of the base component in some form (e.g., for a certain configuration of the component). Modifier names must be written in camel case and be separated from the component name by two hyphens. The class should be included in the HTML in addition to the base component class.

/* Core button */
.Button { /* … */ }
/* Default button style */
.Button--default { /* … */ }
<button class="Button Button--default" type="button">…</button>

ComponentName-descendentName

A component descendent is a class that is attached to a descendent node of a component. It's responsible for applying presentation directly to the descendent on behalf of a particular component. Descendent names must be written in camel case.

<article class="Tweet">
  <header class="Tweet-header">
    <img class="Tweet-avatar" src="{{src}}" alt="{{alt}}">
    …
  </header>
  <div class="Tweet-bodyText">
    …
  </div>
</article>

These CSS selectors will be applied to the HTML above.

.Tweet {
  // styles
}
.Tweet-header {
  // styles
}
.Tweet-avatar {
  // styles
}
.Tweet-bodyText {
  // styles
}

ComponentName.is-stateOfComponent

Use is-stateName to reflect changes to a component's state. The state name must be camel case. Never style these classes directly; they should always be used as an adjoining class.

This means that the same state names can be used in multiple contexts, but every component must define its own styles for the state (as they are scoped to the component).

.Tweet { /* … */ }
.Tweet.is-expanded { /* … */ }
<article class="Tweet is-expanded">
  …
</article>

Sass / SCSS Usage

In order to improve code readability and apply the DRY (Don't Repeat Yourself) principal, use Sasss' Referencing Parent Selector & to both nest and prepend the Component name to the CSS selector.

Taking the Twitter CSS example above, we can apply this usage to improve the code to the following:

These CSS selectors will be applied to the Tweet HTML above.

.Tweet {
  // container styles

  &-header {
    // .Tweet-header decendent styles
  }

  &-avatar {
    // .Tweet-avatar decendent styles
  }

  &-bodyText {
    // .Tweet-bodyText decendent styles
  }

  &--large {
    // .Tweet--large modifier style.
  }

  &.is-expanded {
    // .Tweet.is-expanded state styles
  }
}
Clone this wiki locally