Should you use Atomic CSS in your design system implementation?

Individual "atomic classes" from Atomic CSS seem to be fairly similar to the concept of "design tokens". Both are restricted sets of values that are used extensively across the codebase for styling purposes. Each atomic class can be matched with a single design token value.

Having a single CSS class for each tokenized value means that we can save a ton of space by re-using that class across components (compared to having to duplicate the property declaration with the tokenized value in individual component classes).

Adding new components should not have any additional impact on the size of a singleton stylesheet, because we don't have to define any new classes (given that our component uses already existing design tokens).

Having a dedicated utility for each styling need means that we're able to adjust styling behaviour on a per-use case basis (see an example provided in the "The case for Atomic CSS" section below).

Besides, our selected styling solution (Vanilla Extract) provided an integrated way to generate atomic classes (a Sprinkles framework). This allowed us to leverage the power of TypeScript to ensure correct token names are used and also enjoy the TypeScript autocompletion when authoring the styles.

With Atomic CSS your selectors have the same CSS specificity (0-1-0), so whichever one wins the conflict depends on the source order. There are two problems with that:

• The source order is usually controlled by the tooling that generates the Atomic CSS
• Multiple conflicts might require different source order resolutions that conflict with each other

This requires you to avoid any conflicts when applying your utility classes, which can become very tricky in some cases. E.g. you need to reset a margin on an element, but you can't use an atomic class for that because this margin can be redefined by another component variant (or by the user); this makes you use an element selector for that, but this might trigger unwanted changes in the unrelated element in consuming application, so you have to be more precise and use something like hr:where(.your-atomic-class) to keep the element selector specificity (0-0-1) but scope your selector to the elements with your-atomic-class applied.

This is a known weak spot of Atomic CSS: if you need to use different property values based on some condition (e.g. :hover or :focus or any other pseudoclass, media query or container query) - you'll need to generate a separate class for that. If you need a lot of values at a multitude of conditions the size of your stylesheet might balloon uncontrollably. You can try to use JS to detect the condition and apply the proper classes for you, but that might have performance implications.

That said, the exact performance impact depends on the amount of values and conditions required by your Design System. It's better to measure the impact (by stubbing additional conditions and values) before jumping to any conclusions. E.g. for our design system the measurements suggest that we would have to add 15 more conditions (and/or values) to exhaust our performance budget (and we're unlikely to add that much).

The Atomic CSS implies that a restricted set of styles gets reused over and over again in different contexts. You might not see any performance/maintenance benefits if your Design System isn't based on design tokens or doesn't follow a restricted set of values (like a palette of colours, set of spacing values, etc.).

By its nature, Atomic CSS is used across any boundaries that you can draw within your Design System (be it component groups or individual components). Therefore if your Design System ever grows so big that you want to split it — the Atomic CSS becomes a shared part that might prevent you from splitting it effectively.

Setting up (and having to maintain) the tooling to generate Atomic CSS can be an unjustifiable burden for some people. It can also become a barrier if someone new is trying to contribute to your Design System.