Understanding Atomic CSS and Facebook’s Stylex: Concepts, Trade‑offs, and Practical Usage

Three years ago Facebook began rethinking its design system, moving from CSS‑module based styling to an Atomic CSS‑in‑JS solution called stylex , which reduced the homepage stylesheet size by at least 80%.

Atomic CSS concept : each individual style declaration becomes its own class (an “atom”). For example, a full‑width, full‑height, red background square can be expressed as .w-full { width: 100%; } , .h-full { height: 100%; } , .bg-red { background-color: red; } and used with <div class="w-full h-full bg-red">Square</div> .

Trade‑offs : While many libraries (Acss, UnoCSS, Tailwind) share the same atomic idea, traditional scoped CSS or CSS‑in‑JS still duplicate identical rules across components, inflating bundle size. Atomic CSS eliminates duplication by reusing atoms across multiple npm packages, keeping the final stylesheet size stable even as project complexity grows.

In large‑scale projects, repeated definitions such as .corp-button { height: 100%; width: 100%; } and .corp-input { height: 100%; width: 100%; font-weight: 500; } illustrate the redundancy problem; atomic classes like .w-full , .h-full , and .font-normal can replace them, dramatically shrinking the CSS payload.

When project complexity rises, new components often introduce new class names, causing stylesheet bloat. With Atomic CSS, the same atoms are reused, so the stylesheet size plateaus after a certain point, unlike traditional approaches where each new feature adds more CSS.

Atomic CSS also reduces the risk of style “leakage” across modules because each element’s appearance is assembled from independent atoms, eliminating unintended side effects when a shared class is modified.

Results at Ctrip Business Travel : Switching the international site to an atomic approach cut the initial CSS download from 694 KB (domestic app) to 13.2 KB, a 96 % reduction. Similar gains were observed on the domestic PC homepage, where a query‑box component’s CSS shrank to near‑zero after atomic extraction.

Stylex basics : Stylex uses Babel to compile stylex.create definitions into atomic class names. Example:

import * as stylex from '@stylexjs/stylex';
// stylex.create creates atomic styles
const styles = stylex.create({
  root: {
    backgroundColor: 'red',
    padding: '1rem',
    paddingInlineStart: '2rem'
  },
  title: { backgroundColor: 'blue' },
  dynamic: (opacity) => ({ opacity })
});
function HomePage() {
  return (
Stylex
Introduction to the basics of stylex.
);
}
export default HomePage;

The compiled CSS looks like:

.x1uz70x1:not(#\#){padding:1rem}
.x1t391ir:not(#\#):not(#\#){background-color:blue}
.xrkmrrc:not(#\#):not(#\#){background-color:red}
.x1u4uod0:not(#\#):not(#\#){opacity:var(--opacity,revert)}
.xld8u84:not(#\#):not(#\#){padding-inline-start:2rem}

stylex.defineVars & stylex.createTheme : Variables can be declared with stylex.defineVars and overridden with stylex.createTheme to build themable components. Example token definition and themed button:

// src/components/ButtonTokens.stylex.ts
import * as stylex from '@stylexjs/stylex';
export const buttonTokens = stylex.defineVars({
  bgColor: 'green',
  textColor: 'red',
  cornerRadius: '4px',
  paddingBlock: '4px',
  paddingInline: '8px'
});
// src/components/Button.ts
import * as stylex from '@stylexjs/stylex';
import './ButtonTokens.stylex';
import { buttonTokens } from './ButtonTokens.stylex';
const styles = stylex.create({
  base: {
    borderWidth: 0,
    backgroundColor: buttonTokens.bgColor,
    color: buttonTokens.textColor,
    borderRadius: buttonTokens.cornerRadius,
    paddingBlock: buttonTokens.paddingBlock,
    paddingInline: buttonTokens.paddingInline
  }
});
function Button(props: { theme?: stylex.Theme
}) {
  return
This is Single Button
;
}
export default Button;

Using the component with a custom theme:

import * as stylex from '@stylexjs/stylex';
import Button from './components/Button';
import { buttonTokens } from './components/ButtonTokens.stylex';
const otherTheme = stylex.createTheme(buttonTokens, {
  bgColor: '#000',
  textColor: 'yellow',
  cornerRadius: '4px',
  paddingBlock: '4px',
  paddingInline: '8px'
});
function HomePage() {
  return (
);
}
export default HomePage;

The two buttons render with different colors, demonstrating how themes are applied via CSS variables with proper priority handling.

Outlook : While Stylex still has some ecosystem gaps, Atomic CSS – whether implemented via Tailwind‑style utilities or CSS‑in‑JS solutions like Stylex – offers a promising path for reducing stylesheet size, improving maintainability, and enabling themable component libraries in large front‑end codebases.