BEM

BEM (Block Element Modifier) is the naming convention used for all CSS classes in Lumbermill. It makes class names self-documenting and avoids selector specificity conflicts.

Block

A block is a standalone component that is meaningful on its own.

<div class="card"></div>
<nav class="nav"></nav>
<button class="button"></button>

Multi-word block names use a single hyphen:

<div class="team-member"></div>
<section class="hero-banner"></section>

Element

An element is part of a block with no standalone meaning. Prefix with __ (two underscores).

<article class="card">
    <img class="card__image" src="..." alt="..." />
    <h2 class="card__title">Title</h2>
    <p class="card__body">Body text</p>
    <a class="card__link" href="...">Read more</a>
</article>

Modifier

A modifier changes the appearance or state of a block or element. Prefix with -- (two hyphens). Always apply a modifier alongside the base class.

<!-- Block modifier — changes the whole card -->
<article class="card card--featured"></article>

<!-- Element modifier — changes just the button -->
<a class="card__link card__link--disabled" href="...">Read more</a>

Complete example

<article class="card card--featured">
    <img class="card__image" src="..." alt="..." />
    <div class="card__content">
        <h2 class="card__title">Title</h2>
        <p class="card__body">Body text</p>
    </div>
    <a class="card__link" href="...">Read more</a>
</article>

.card {
    padding: 1rem;

    &__image { width: 100%; }
    &__content { padding: 1rem; }
    &__title { font-size: 1.25rem; }
    &__body { color: $colour-text; }
    &__link { display: inline-block; }

    &--featured {
        border: 2px solid $colour-primary;
    }
}

Common mistakes

Do not nest element names

An element always takes the block name as its prefix — not its parent element. BEM class names are flat.

<!-- Bad — double underscore nesting -->
<article class="card">
    <div class="card__content">
        <h2 class="card__content__title">Title</h2>
    </div>
</article>

<!-- Good — flat element names -->
<article class="card">
    <div class="card__content">
        <h2 class="card__title">Title</h2>
    </div>
</article>

Do not use BEM for utility classes

BEM is for components. Global utility classes (spacing, typography helpers) should use a different prefix.

<!-- Good — utility class alongside a BEM component -->
<article class="card u-mt-md"></article>

Do not apply a modifier without the base class

<!-- Bad -->
<article class="card--featured"></article>

<!-- Good -->
<article class="card card--featured"></article>

BEM