CSS conventions
PostCSS
We use postcss-preset-env
and CSS features from stage 3+ (opens new window).
Reduce cognitive load
- Use as much native CSS features as possible;
- SHOULD not use PostCSS magic like
&
(exceptions: pseudo-elements and pseudo-classes and@media
rules); - SHOULD not use nesting, because BEM names are unique enough (exceptions: pseudo-elements and pseudo-classes and
@media
rules);
CSS Class Naming conventions
We use ITCSS (opens new window): superset of BEM (opens new window) CSS methodology.
- ITCSS architecture (opens new window)
- ITCSS: Harry Roberts - Managing CSS Projects with ITCSS (video) (opens new window)
- BEM quick-start (opens new window)
- Battling BEM CSS: 10 Common Problems And How To Avoid Them (opens new window)
Additionally, we prefer to use camelCase, as follows:
.blockName {
}
.blockName__elementName {
}
.blockName__elementName--modifierName {
}
Utility classes
Along with our BEM based classes we have our utility classes. For all components and page specific classes we use BEM but when it comes to utility classes we have chosen to follow Tailwind 3 (opens new window). This makes it easier for any new developer to come in to our project and know classnames without even having to go through our docs. Examples of utility classes
<div class="flex justify-center">
<article class="mb-small"></article>
<article class="mb-small"></article>
</div>
Using utility classes
Whenever a function can be performed using utility classes then the utility class should be used instead of creating custom BEM classes. One of the most common example is margin and padding utility classes that are needed in almost every page.
<div class="blockName p-large">
<section class="mb-small background-neutral-04"></section>
<article class="mb-small">
</div>
Using BEM along with utility classes
Sometimes a page will require its custom CSS and in that case its good to combine utility classes along with the BEM bases classes for the page/component.
<article class="card radius-lg col-md-6">
<!-- card content -->
</article>
This article (opens new window) provides excellent guidelines for using BEM, utility classes and using them together.
Files naming conventions
Filenames should also use BEM + camelCase notation (same naming conventions above for CSS/PostCSS). The file structure for a CSS component would look like this:
/components
/inputGroup
inputGroup.css
inputGroup--small.css
inputGroup--big.css
inputGroup.md
. . .