SMACSS: A Naming Convention for CSS Scalability

Why it exists

CSS in large projects often becomes a tangled mess of overrides and specificity wars. Without a system, developers can't safely add or change styles without causing unintended side effects. SMACSS was created to provide a consistent approach for structuring CSS to improve maintainability and scalability on projects with long lifespans and multiple contributors.

The mental model

Think of SMACSS as creating labeled buckets for your CSS rules. Instead of one giant, unpredictable stylesheet, you categorize every rule based on its purpose. Is it a default style for a basic HTML element (Base)? Does it define a major page section (Layout)? Is it a reusable, self-contained component (Module)? This categorization prevents styles from bleeding into each other unexpectedly.

How it works

SMACSS proposes five distinct categories. First, Base rules are element selectors setting application-wide defaults (like body, a, input). Second, Layout rules divide the page into major sections (like .l-header, .l-sidebar). Third, Module rules are for reusable, discrete UI components (like .card, .button). Fourth, State rules modify a module or layout's appearance (like .is-hidden, .is-active). Fifth, Theme rules are optional overrides for changing the visual look. A common convention is to prefix class names, such as l- for Layout and is- for State, to make the rule's purpose obvious from the HTML.

When to use it

Use SMACSS principles on large, long-lived projects with multiple developers, especially when you are not using a component-based JavaScript framework with scoped styles (like React with CSS Modules). It provides a shared vocabulary and structure that prevents CSS decay over time.

When not to use it

For small, single-page projects, the organizational overhead of SMACSS might be unnecessary. Modern component frameworks with built-in style scoping (like Vue's Single-File Components or styled-components) solve many of the same global namespace problems that SMACSS was designed to address, making a strict SMACSS methodology less critical in those environments.

One canonical example

A login form could be a Module named .form-login. The major page regions it sits in, like a header and a main content area, would be defined by Layout rules like .l-header and .l-main. The default styles for the input and button elements are set by Base rules. When the user types an incorrect password, a State class like .is-error is added to the form to show a red border.