SMACSS stands for Scalable and Modular Architecture for CSS. It is a flexible way to classify stylesheet rules—not a framework to install—using five categories: Base, Layout, Module, State, and Theme. The categories help a team see what a rule is responsible for and keep reusable components from becoming entangled with a particular page.
What SMACSS means—and what it does not
Jonathan Snook describes SMACSS as “more style guide than rigid framework.” The approach is a set of ideas for organizing CSS, not a package, compiler, or required directory structure. You can use the whole method or adopt only the conventions that solve problems in your project.
As an Amazon Associate I earn from qualifying purchases.
The SMACSS book was written in 2011, and its site says it remains online for archival and educational purposes. Treat it as an established methodology rather than a newly updated specification. Its value is the mental model: decide whether a rule sets a general default, arranges a page, styles a reusable component, expresses a condition, or supplies a theme.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWhat are the five SMACSS categories?
| Category | What it covers | Example |
|---|---|---|
| Base | Broad defaults for elements wherever they appear. | Default body typography, link color, or heading margins. |
| Layout | Major and minor regions that arrange the page. | Header, main content column, sidebar, or grid container. The guide suggests l- as a possible prefix. |
| Module | Discrete interface components intended to be reusable. | Navigation, a callout, a form, or a card. |
| State | A condition or variation that changes how something is presented. | Expanded, hidden, active, or a view-specific variation. The guide suggests is- as a possible prefix. |
| Theme | An optional layer for appearance variations that may affect other categories. | Alternate colors, imagery, or other look-and-feel choices. |
These are ways to understand a rule’s role, not five mandatory files. A project could put the categories in separate files, group them within one stylesheet, or use a different build structure. What matters is making responsibilities clear. Some rules sit near category boundaries; noticing that overlap can help prevent unrelated concerns from becoming tightly coupled.
#1 Best Overall
How to organize CSS with SMACSS
- Inventory what the stylesheet already does. Identify broad element defaults, page regions, repeated interface patterns, conditional styles, and any real alternate appearance requirements. Classify by purpose, not by the file where a rule happens to live.
- Keep Base broad. Use Base for defaults that should generally hold across the site. Avoid placing a one-off component treatment in a global element rule.
- Separate page arrangement from component appearance. Put structural placement in Layout and the component’s own styling in a Module. A navigation component should remain usable in a header or another context without inheriting its visual identity from the location that contains it.
- Name module variations explicitly. When a module has a meaningful variation, use a clear class or subclass to express it rather than relying on a long chain of ancestor selectors. The SMACSS book demonstrates subclassing a base module for this purpose.
- Make states readable. State classes should communicate a condition such as active or expanded. Prefixes like
is-can help distinguish state from a component’s stable identity, but they are conventions, not required syntax. - Add a Theme layer only when there is a real need. If the product supports alternate appearances, separating theme-related choices can clarify how those variants affect modules, layout, base styles, or states. A project with no such requirement does not need a separate theme category in its file structure.
- Write down the team’s conventions. Agree where styles belong, how modules and variations are named, and how rules are loaded. Consistent use matters more than selecting a particular prefix or folder scheme.
A small example
This illustrative example keeps page arrangement separate from the reusable notice component and its state. The names are one possible convention, not required SMACSS syntax.
/* Layout: page placement and structure */
.l-content {
max-width: 72rem;
margin-inline: auto;
padding: 1.5rem;
}
/* Module: reusable component appearance */
.notice {
border: 1px solid #9aa;
padding: 1rem;
}
/* State: a condition of the module */
.is-hidden {
display: none;
}The same .notice can appear in another layout without acquiring a dependency on .l-content. In a real application, ensure the state class is applied only when the content should be hidden and that the class name’s meaning is documented for the team.
Selector and HTML choices
Favor explicit module classes over selectors that identify a component only through its position in a page, such as a deeply nested descendant selector. Location-dependent selectors can make a component harder to move and can increase specificity conflicts. Explicit module names and subclasses make the intended relationship easier to see, although they do not eliminate conflicts caused by specificity or stylesheet load order.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesSMACSS works with HTML5 elements. Semantic tags can clarify document structure, but a semantic element is not automatically a unique identifier for a visual module. Use HTML for meaning and structure, and classes for the styling roles that need to be explicit.
What SMACSS does not prescribe
- A fixed project layout: the categories need not map one-to-one to files or folders.
- Mandatory prefixes:
l-andis-are suggested naming aids, not a parser-enforced grammar. - A separate theme system for every site: Theme is optional when alternate appearances are not a genuine project requirement.
- A universal winner over other CSS architectures: a useful comparison depends on naming, component and layout separation, HTML coupling, specificity practices, and the team’s existing workflow. The SMACSS guidance alone does not establish a current comparative ranking.
Visual-check screenshots without adding CSS architecture to your app
After applying a CSS organization, you may want screenshots of rendered pages to check how the layout and components appear. That is a visual QA step; it does not change how SMACSS categories should be organized. ScreenshotNeo is a website screenshot API and MCP server for developers. For a one-request capture of a page as WebP:
ScreenshotNeo API documentation
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month, with no card required.
Recommended Free Tools
Rank #4
- Used Book in Good Condition
Common mistakes when adopting SMACSS
- Turning categories into bureaucracy. Do not create five empty files just because there are five categories. Choose an organization the project can maintain.
- Styling a component through its location. A selector tied to a particular page ancestor may break portability. Give the component its own class and express genuine variations deliberately.
- Calling every variation a state. Use a state label for a condition, not as a catch-all name for a component’s stable identity. Keep state naming understandable and consistent.
- Assuming categories prevent cascade conflicts automatically. CSS specificity and load order still matter. Keep selectors intentional and establish a predictable loading and override policy.
- Adding a theme layer without a use case. Theme is useful when alternate appearances need to be managed; otherwise, extra separation may add maintenance without clarifying the code.
Further reading
Jonathan Snook’s book, Scalable and Modular Architecture for CSS, can be read online and downloaded in e-book formats from the SMACSS site. The free online edition means purchasing a copy is not necessary to learn the method.
Frequently Asked Questions
Does SMACSS require Sass, Less, or a particular CSS build tool?
No. SMACSS describes how to think about and organize CSS rules; it does not depend on a particular preprocessor or build tool.
Can a project use SMACSS conventions alongside its existing naming system?
Yes. It is flexible guidance, so a team can adopt selected principles and adapt naming and organization to its codebase.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →
