Atomize is a library of atomic CSS classes.

Low specificity. Predictable styles.

Utilities apply a single rule or a single piece of functionality. They are designed to be highly reusable.

For more information of this approach to CSS, see:

• On the Growing Popularity of Atomic CSS
• CSS Utility Classes and "Separation of Concerns"

This project is heavily inspired by Tailwind, Basscss and Tachyons.

Using Atomize

Atomize purposefully keeps things simple. There is no CLI. There are not configuration files. There are no dependencies. There is no NPM install. Just copy the files you require into your project and include them in the usual way.

The compiled CSS is also available to use from the UNPKG CDN.

<link rel="stylesheet" href="https://unpkg.com/@pixelpusher/atomize" />

Staying out of peoples way

Atomize aims to be style neutral.

• Some margin classes and grid classes are included as a reference implementation and commented out. Define your own depending on your design and use case.
• colors.scss is included as an example of the recommended way to handle colors. Define your own depending on your design.
• Atomize does not include breakpoints. Define your own.

Grid classes

The amount of custom layout designs that could be implemented with CSS grid are almost infinite. You can use CSS grid for everything from a small widget to the entire layout of a page. Abstracting such a large amount of options into utility classes is not feasible. Define your own classes for using CSS grid.

At-A-Glance Understandability

Atomize avoids overly abbreviated class names and instead strives for classes that are human-readable and easily understandable.

Escaping special characters

Atomize makes use of the @ symbol, percentage sign, and colons (:) in class names.

These characters have a special meaning in CSS. These characters can be escaped with a backslash to remove their special meaning.

State Variants

To style elements on hover, focus, active or focus-within, use a hover:, focus:, active:, focus-within: prefix.

e.g. given the following classes, the button will have a pink background, while on hover it will have a blue background.

.bg-pink { background-color:pink; }

.hover\:bg-blue:hover { background-color: var(--blue); }

<button class="bg-pink hover:bg-blue">click</button>

Handling media queries

Breakpoints should be defined as Sass variables (CSS custom properties cannot be used for this purpose).

Breakpoint Suffixes

HTML classes that have an impact only at specific screen sizes have a @breakpoint-name prefix.

e.g.:

.font-xl {
  font-size: 75px;
}

@media (max-width: $breakpoint-mobile) {
  .\@sm\:font-l {
    font-size: 50px;
  }
}

Given the following markup, a h1 would be 50 pixels on mobile and 75 pixels on all larger screens.

<h1 class="font-xl @sm:font-l">Lorem Ipsum Heading</h1>

Opinionated Styles

base.scss is opinionated.

It sets box-sizing to border-box for all elements rather than the browser default of content-box.

base.scss also makes working with REM units easier.

Pixel values are generally more intuitive than relative sizes (em's and rem's). However, rem values should be used to size text in order to cater for users who want to enlarge the size of text using there browser settings. Understanding the pixel value of these relative sizes is made obvious.

1rem is computed as 10px. 1.6rem is computed as 16px. 1.7rem is computed as 17px. 5rem is computed as 50px. etc.

Font sizes

It's important to avoid skipping heading levels when structuring your document, as it confuses screen readers. For example, after using an <h2> in your code, the next heading used should be either <h2> or <h3>. If you need a heading to look bigger or smaller to match a specific style, use CSS to override the default size.

Atomize applies styling directly to HTML heading elements, while also defining classes for overrides:

h1, .h1 {}
h2, .h2 {}
h3, .h3 {}
h4, .h4 {}
h5, .h5 {}
h6, .h6 {}

Styling shadow DOM

Classes defined outside of shadow DOM don't work inside of shadow DOM. Atomize does, however, define some CSS custom properties, which can be used. All colors and font sizes are defined as CSS custom properties.