Understanding CSS Architecture: Part 2 - Naming Conventions

Naming things is famously one of the hardest problems in computer science. In CSS, good naming conventions are crucial for maintainability. Let's explore the major approaches.

Why Naming Matters#

Clear naming provides:

• Predictability - Know what a class does by reading it
• Consistency - Team-wide conventions reduce confusion
• Encapsulation - Avoid unintended style collisions
• Documentation - Code becomes self-documenting

BEM: Block Element Modifier#

BEM organizes styles around blocks, their elements, and modifiers:

/* Block */
.card { }

/* Element (part of block) */
.card__header { }
.card__title { }
.card__body { }
.card__footer { }

/* Modifier (variation) */
.card--featured { }
.card--compact { }
.card__title--large { }

Pros#

• Clear hierarchy and relationships
• Prevents nesting-related specificity issues
• Widely understood in the industry

Cons#

• Verbose class names
• Can feel rigid for simple cases
• HTML can become cluttered

CUBE CSS#

CUBE (Composition, Utility, Block, Exception) is a methodology that embraces modern CSS:

<article class="card [ flow ] [ featured ]" data-variant="highlight">
    <h2 class="[ text-lg font-bold ]">Title</h2>
    <p>Content here...</p>
</article>

/* Composition - layout primitives */
.flow > * + * {
    margin-block-start: var(--flow-space, 1em);
}

/* Block - component-specific */
.card {
    padding: var(--space-md);
    background: var(--color-surface);
}

/* Exception - state variations */
.card[data-variant="highlight"] {
    border-left: 4px solid var(--color-accent);
}

The Grouping Convention#

Notice the [ ] brackets? They're optional visual grouping:

<!-- Reads as: composition classes | utility classes | state classes -->
<div class="[ stack cluster ] [ gap-md pad-lg ] [ is-active ]">

Utility-First (Tailwind-style)#

Compose UIs from single-purpose utility classes:

<article class="p-4 bg-white rounded-lg shadow-md">
    <h2 class="text-xl font-bold text-gray-900">Title</h2>
    <p class="mt-2 text-gray-600">Content...</p>
</article>

Pros#

• Extremely fast development
• No naming decisions for one-off styles
• Built-in design constraints

Cons#

• HTML can become verbose
• Requires build tooling for production
• Learning curve for class names

Hybrid Approaches#

Many teams combine approaches:

<article class="card p-4 shadow-md">
    <h2 class="card__title text-xl font-bold">
        Title
    </h2>
</article>

/* Component provides structure */
.card {
    display: flex;
    flex-direction: column;
    background: var(--color-surface);
    border-radius: var(--radius-md);
}

/* Utilities handle spacing, colors */

Choosing an Approach#

Consider:

• Team size - Larger teams benefit from stricter conventions
• Project scale - Complex apps need more structure
• Tooling - Some approaches need build steps
• Team experience - Familiar conventions reduce friction

Conclusion#

There's no universally "best" naming convention. The best choice depends on your team, project, and preferences. Consistency matters more than the specific approach chosen.

If you haven't already, check out Part 1 - Foundations for the principles that underpin good CSS architecture.

In Part 3, we'll explore modern CSS features that reduce the need for complex class hierarchies.