Atomic CSS: Concepts, Examples, Framework Comparison, and Practical Evaluation

What is Atomic CSS

According to the article "Let’s Define Exactly What Atomic CSS is", Atomic CSS is an approach to CSS architecture that favors small, single‑purpose classes named based on visual function.

Atomic CSS is the approach to CSS architecture that favors small, single‑purpose classes with names based on visual function.

In Chinese: 原子化 CSS 是一种 CSS 的架构方式，它倾向于小巧且用途单一的 class，并且会以视觉效果进行命名。

.bg-blue { background-color: #357edd; }
.f1 { font-size: 3rem; }
.m0 { margin: 0; }

Typical CSS Writing Practices

Traditional CSS often results in many component‑specific classes, leading to duplication and difficulty in reuse. An example component (a media record) is shown with HTML and CSS.

<div class="media">
  <a href="https://www.zcygov.cn/" class="img">
    <img width="40" src="logo.png" alt="zcy" />
  </a>
  <div class="bd">@小明 14 分钟之前</div>
</div>
<style>
  .media { margin: 10px; }
  .media, .bd { overflow: hidden; _overflow: visible; zoom: 1; }
  .media .img { float: left; margin-right: 10px; }
  .media .img img { display: block; }
</style>

When the design changes (e.g., moving the avatar to the right), a new class .imgExt with float: right is added.

<div class="media">
  <a href="https://www.zcygov.cn/" class="imgExt">
    <img width="40" src="..." alt="zcy" />
  </a>
  <div class="bd">@小明 14 分钟之前</div>
</div>
<style>
  .media .imgExt { float: right; margin-left: 10px; }
</style>

Further requirements, such as reducing font size when the component appears in a right‑rail container, lead to additional CSS rules.

#rightRail .bd { font-size: smaller; }

Problems with This Approach

Every visual change requires a new CSS rule, causing class proliferation and tight coupling between CSS and business components.

Many rules are context‑specific, making reuse difficult.

New requirements often conflict with existing rules, requiring overrides or nested classes.

Duplicate CSS files arise because developers copy‑paste styles instead of using @import .

Deep nesting and use of the & selector reduce readability and searchability.

CSS Framework Overview

Atomic CSS

Utility‑first frameworks (e.g., TailwindCSS, WindiCSS) provide ready‑made single‑purpose classes, eliminating the need to write custom CSS.

OOCSS (Object‑Oriented CSS)

Focuses on separating structure from skin and containers from content, encouraging reusable objects.

SMACSS

Classifies CSS into Base, Layout, Module, State, and Theme categories.

BEM

Uses a block‑element‑modifier naming convention to create flat, non‑nested class structures.

ITCSS

Organises CSS into layers: Settings, Tools, Generic, Elements, Objects, Components, and Utilities.

Why We Chose Atomic CSS

Our backend‑admin project has a mature component library and low CSS complexity. Atomic CSS (via WindiCSS) offers the lowest adoption cost, no need to define naming rules, and immediate utility classes.

How Atomic CSS Solves the Problems

By using utility classes, we avoid naming conflicts, reduce nesting, eliminate duplicate CSS files, and speed up development. Example:

<div class="overflow-hidden mr-1">
  <a href="https://www.zcygov.cn/" class="float-left mr-1">
    <img width="30" src="logo.png" alt="zcy" />
  </a>
  <div class="overflow-hidden text-sm">@小明 14 分钟之前</div>
</div>

Changing the avatar side is as simple as swapping float-left for float-right .

Usage Experience

VSCode extension WindiCSS Intellisense greatly improves productivity.

Initially, developers need to consult the official docs to learn utility class names.

Design tokens can be configured to align utilities with visual design specifications.

import { defineConfig } from 'windicss/helpers';
import colors from 'windicss/colors';
export default defineConfig({
  theme: {
    extend: {
      transitionProperty: { width: 'width' },
      screens: { sm: '640px', md: '768px', lg: '1024px', xl: '1280px' },
      colors: { gray: colors.coolGray, blue: colors.sky, red: colors.rose, pink: colors.fuchsia },
      fontSize: {
        xs: '.75rem', sm: '.875rem', tiny: '.875rem', base: '14px', lg: '1.125rem', xl: '1.25rem',
        '2xl': '1.5rem', '3xl': '1.875rem', '4xl': '2.25rem', '5xl': '3rem', '6xl': '4rem', '7xl': '5rem'
      }
    }
  }
});

Remaining Challenges

Utility‑first frameworks can lead to very long class lists in HTML, reducing readability and making reuse harder. For example, a button may require dozens of utility classes.

<button class="bg-blue-400 text-sm text-white font-mono font-light py-2 px-4 border-2 border-rounded border-blue-200">Button</button>

Workarounds include attribute‑based utilities, shortcuts, and directives, but the core issue of verbose class strings remains.

Developers may also create JavaScript constants to hold class strings, which merely shifts the naming problem.

Conclusion

Atomic CSS can effectively address naming conflicts, code duplication, and maintenance overhead, but it is not a silver bullet. Teams must weigh project complexity, developer familiarity, and the trade‑offs of utility‑first approaches before adopting a framework.

References

Challenging CSS Best Practices – https://www.smashingmagazine.com/2013/10/challenging-css-best-practices-atomic-approach/

Let’s Define Exactly What Atomic CSS is – https://css-tricks.com/lets-define-exactly-atomic-css/

WindiCSS – https://github.com/windicss/windicss

TailwindCSS – https://github.com/tailwindlabs/tailwindcss