What Is SMACSS: Modular CSS Architecture Guide

SMACSS, which stands for Scalable and Modular Architecture for CSS, is a flexible design methodology created to bring structure, consistency, and maintainability to front-end codebases. Rather than acting as a rigid framework or library, SMACSS provides a set of guidelines for organizing CSS rules into distinct, manageable buckets. This article examines the core principles of SMACSS and explains its five fundamental categories: Base, Layout, Module, State, and Theme.

Understanding SMACSS

Developed by front-end developer Jonathan Snook, SMACSS addresses the common problems of CSS bloat, specificity conflicts, and tight coupling in growing applications. It promotes writing modular code by categorizing styles based on their purpose. By enforcing clear naming conventions and structural boundaries, SMACSS makes CSS easier to write, read, scale, and maintain across teams.

The Five SMACSS Categories

The core of the SMACSS methodology is dividing CSS rules into five specific categories:

1. Base Rules

Base rules define the default styling for raw HTML elements across an entire website or application. They include resets, normalize stylesheets, and broad element-level defaults such as headings, input fields, paragraphs, and anchor tags.

Base rules should almost exclusively target element selectors (e.g., body, p, a, h1) without using classes or IDs. For example:

html {
  font-size: 16px;
  box-sizing: border-box;
}

a {
  color: #0066cc;
  text-decoration: none;
}

2. Layout Rules

Layout rules divide a page into major structural sections. These components dictate where elements sit on the page, such as headers, footers, sidebars, content regions, and grid systems.

Layout rules frequently use classes prefixed with l- or layout- to differentiate them from smaller UI components. While layout elements may contain modules, they rarely dictate the appearance of the modules inside them. For example:

.l-header {
  width: 100%;
  height: 60px;
}

.l-sidebar {
  float: left;
  width: 25%;
}

3. Module Rules

Modules represent the reusable, self-contained UI components of a website. Examples include navigation bars, dialog boxes, cards, buttons, and product widgets. A module should exist independently of its surrounding layout so that it can be moved anywhere on a page without breaking.

In SMACSS, module styles rely strictly on class selectors rather than tag or ID selectors to avoid specificity issues. Sub-components within a module are nested conceptually via class names:

.card {
  border: 1px solid #ccc;
  padding: 16px;
}

.card-title {
  font-size: 1.25rem;
  font-weight: bold;
}

4. State Rules

State rules describe how a module or layout looks when it enters a specific state, such as active, inactive, expanded, collapsed, loading, or hidden. States typically change via JavaScript or pseudo-classes.

State classes are applied directly to the element they modify and are conventionally prefixed with is- (such as is-active, is-hidden, or is-disabled). These rules may override base or module styles:

.is-hidden {
  display: none;
}

.tab.is-active {
  border-bottom: 2px solid #0066cc;
  font-weight: bold;
}

5. Theme Rules

Theme rules define visual styles—primarily colors, borders, and background imagery—that may need to change across an entire interface. While not every project requires a theme layer, it is essential for sites that support multiple skins, branding options, or dark and light modes.

Theme rules separate primary layout and structural styles from skinning attributes, making it easy to swap appearances without altering the underlying component structure:

/* In a dark-theme stylesheet */
.card {
  background-color: #222;
  color: #fff;
  border-color: #444;
}