Best practices for naming classes

A well-named class tells you what an element is and what role it plays — without requiring you to read the CSS. Poor class names create confusion as a project grows. These guidelines will save you hours of debugging and make your projects straightforward to hand off to anyone else.

Use BEM as your naming foundation

BEM (Block, Element, Modifier) is the most widely adopted CSS naming convention. It structures names into three parts:

• Block — the standalone component: .card, .nav, .form
• Element — a part of the block: .card__title, .nav__link, .form__label
• Modifier — a variation of the block or element: .card--featured, .btn--large, .btn--primary

The double underscore (__) separates a block from its element. The double hyphen (--) separates a block or element from its modifier.

BEM in practice

/* Block */
.card { }

/* Elements */
.card__image { }
.card__title { }
.card__body { }
.card__footer { }

/* Modifiers */
.card--featured { }
.card--compact { }
.card__title--large { }

An element in HTML might look like this:

<article class="card card--featured">
  <img class="card__image" src="..." alt="...">
  <h2 class="card__title card__title--large">Title</h2>
  <div class="card__body">Content</div>
</article>

Use kebab-case

CSS class names are case-sensitive. The convention is kebab-case (all lowercase, words separated by hyphens): .hero-section, .nav-link, .cta-button.

Avoid camelCase (.heroSection) and PascalCase (.HeroSection) — these are JavaScript and component conventions, not CSS conventions. Mixing them creates inconsistency and makes grepping for class names harder.

Describe purpose, not appearance

Name classes after what an element does or is, not how it looks right now.

Avoid positional names

Names like .left-column, .top-nav, and .bottom-footer describe where something is on one specific layout. At a different screen size or in a redesign, the position will likely change — leaving you with misleading class names.

Instead, name by role: .sidebar, .main-nav, .page-footer.

Avoid overly specific names

Highly specific names like .homepage-hero-title are brittle. If you move the hero to another page or reuse the title style elsewhere, the class name becomes inaccurate.

Prefer .hero__title (BEM) or .section-title (generic) — names that describe the style’s role without hardcoding its location in the site.

Keep names short but meaningful

There is a balance between brevity and clarity. Single-letter or cryptic abbreviations (.mb, .fs-xl) are fine for a design system you maintain yourself, but confusing for collaborators. Names like .margin-bottom-large or .font-size-extra-large are self-documenting but verbose.

A good rule of thumb: if you can guess what an element looks like from its class name alone, the name is good. If you need to open the CSS to understand it, the name is too abstract.

Organize classes by component

As your project grows, group related classes together in your mental model — and in comments in your CSS. All .card* classes together, all .nav* classes together. Site Designer’s class list in the Design pane is organized alphabetically, which is another reason to pick a consistent prefix per component.