CSS Coding Conventions

BEM

BEM is a methodology used in Core Components that helps to create reusable components through a CSS class naming convention. It makes front-end code semantic, easier to read, understandable and maintainable.

Which Components Use BEM?

The latest Core Component versions use the BEM class naming scheme. To check if a component is using BEM have a look at the README.md file of a component version you're interested in and look for a BEM Description section.

All new components or features employ BEM.

BEM 101

• Block - An independent entity that has meaning on its own and represents a UI section. For example, a navigation, list, tabs or form. A web interface is represented as a hierarchical collection of blocks. Example: cmp-tabs
• Element - Part of a block, to which it's tied semantically and functionally. An element has no meaning outside of the block it belongs to. For example, a navigation item, list item, tab panel or form field. Example: cmp-tabs__tabpanel
• Modifier - Flags set on either blocks or elements, to define properties or states (i.e. to change appearance or behavior). Example: cmp-tabs__tabpanel--active

BEM Example

Simplified example from the Tabs Component markup:

<div class="cmp-tabs">
  <ol class="cmp-tabs__tablist">
    <li class="cmp-tabs__tab cmp-tabs__tab--active">Tab 1</li>
    <li class="cmp-tabs__tab">Tab 2</li>
    <li class="cmp-tabs__tab">Tab 3</li>
  </ol>
  <div class="cmp-tabs__tabpanel cmp-tabs__tabpanel--active">Tab Panel 1 Content</div>
  <div class="cmp-tabs__tabpanel">Tab Panel 2 Content</div>
  <div class="cmp-tabs__tabpanel">Tab Panel 3 Content</div>
</div>

That employs the following BEM notation:

BLOCK cmp-tabs
    ELEMENT cmp-tabs__tablist
    ELEMENT cmp-tabs__tab
        MOD cmp-tabs__tab--active
    ELEMENT cmp-tabs__tabpanel
        MOD cmp-tabs__tabpanel--active

Namespace

The BEM notation used in the Core Components follows the standard BEM naming scheme, but adds an additional namespace prefix cmp- to encapsulate Core Component style rules.

State Modifiers

Some BEM implementations prefix state modifiers (active, disabled etc.) with an "is" keyword block__element--is-state. In Core Components the preferred pattern is to use a standard modifier with no prefix block__element--state.