Naming Conventions

Our CSS components use a BEM naming convention borrowed from SUIT CSS:

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 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="docs/naming-convention.html">
    <img class="u-block" 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: <ComponentName>[-descendentName][--modifierName]

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

ComponentName

The component's name is 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 are written in camel case and 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 { /* … */ }

/* Primary button modifier */
.Button--primary { /* … */ }
<button class="Button Button--primary" 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 are written in camel case.

<article class="Panel">
  <header class="Panel-header">
    …
  </header>
  <div class="Panel-body">
    …
  </div>
</article>

ComponentName.is-stateOfComponent

Use is-stateName to reflect changes to a component's state. The state name is written in 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).

.Button { /* … */ }
.Button.is-active { /* … */ }
<button class="Button is-active">
  ...
</button>