Overview
We follow the BEM (block, element, modifier) naming convention for assigning clear, concise and semantic classes to our HTML elements.
Generally, there are 3 problems that BEM naming conventions try to solve:
- To know what a selector does, just by looking at its name
- To have an idea of where a selector can be used, just by looking at it
- To know the relationships between class names, just by looking at them
BEM Naming
- .block represents the higher level of an abstraction or component.
- .block__element represents a descendent of .block that helps form the .block object.
- .block--modifier represents a different state or version of .block.
.block{}
.block__element{}
.block--modifier{}
A practical example of this would be
.search{} /* Block */
.search__submit{} /* Element */
.search--full{} /* Modifier */
The BEM naming style does not need to be used for elements that have no relationship to parent elements or sit on their own. Remember that BEM is used to clarify code, not to be adhered to without question. The naming of BEM identifiers should follow our naming conventions outlined in this document where possible to create a consistent design language.
The following example provides a more literal example of how classes would be structured for a toast component.
In practice this would appear as as classes that are chained together to style the markup. It is important to note that classes can be nested in other blocks, they do not have to cascade from the blocks.
<div class="co-toast co-toast--success">
<div class="co-toast__icon-left"><i class="co-icon co-icon--tick"></i></div>
<div class="co-toast__label">This is a toast</div>
<div class="co-toast__btn-close">
<button class="button--icon"><i class="co-icon co-icon--close"></button>
</div>
</div>
For illustration purposes, markup is not production ready
The scope of BEM is huge and there are many resources online. This documentation outlines the approaches that Compound follows and should be applied to Markup.
Basic Naming Conventions
The following naming conventions should be used to name classes
- Double Underscores "__" - This should be used for elements
- Double Hyphen "--" - This should be used modifiers
- Single Hyphen "-" - This should be used to replace space or for blocks that have a more descriptive name e.g. alert-slim