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
        . . .