Utility classes

Because so much of the styling is already done in the lower layers, there are times when you just need to change one property. And that's where SmoothCSS utilities shine – they do one thing, and they do it well.

Compared to utility-first approaches you'll find the set of SmoothCSS utilities limited, and the class names long.

This is by design.

Unlike utility-first approaches, SmoothCSS isn't trying to recreate every CSS feature as a class. The global and styling skin layers of SmoothCSS are used for generic or complex styles.

And the class names are long because they are similar to the CSS they implement, making them easy to remember. You'll also find that the effort to write out a long list of utility classes will help you know when a styling skin may be a better fit.

A benefit of having a limited set of utility classes is that they are all included in the SmoothCSS file. As a result there is little benefit to adding a complex build step to find which utility classes are used, and purge unused classes. An additional benefit of this approach is you can safely use dynamic class names in your templates and components.

As utility classes apply a single CSS property, or a group of related properties, they can be grouped by property:

• Alignment
• Border
• Color
• Font size
• Font weight
• Gap
• Margin
• Padding
• Stack
• Visibility
• Wrapper

Alignment

Align text or items in a flexbox or grid.

Border

All the variants of the border and border radius tokens.

Color

Variants of specific colors, and groups of colors to apply to sections of a page and/or components.

Specific colors

Color is applied as either color or background-color depending on whether the design token is for foreground or background.

Button colors

The following color utility classes can be added to the button component class to change the style of the button.

Hard colors, such as primary and error, are reserved for buttons to make primary action clear.

--button-color: var(--color-on-primary);
--button-background: var(--color-primary);
--button-border-color: var(--color-primary);

--button-color: var(--color-on-error);
--button-background: var(--color-error);
--button-border-color: var(--color-error);

--button-background: transparent;
--button-border-color: var(--button-hover-color);

Container colors

Container colors change the color scheme of the container they are applied to. This includes the surface colors, on-surface colors, and outlines.

There are the following container utility classes:

• primary-container
• error-container

Color scheme

SmoothCSS uses the CSS light-dark() function to change the site's theme based on the user's preference for light or dark mode. This approach also allows us to set an explicit color-scheme property to change a page, section of a page, or element to the light or dark version.

The color scheme utility classes set the color scheme for the container they are applied to, and all its decendents. These sections of the page will remain in the chosen color scheme – they will no longer change with the user's preferences.

There are two color scheme utility classes:

• color-scheme-light
• color-scheme-dark

Font size

All the variants of the font step tokens, and the font-size-base.

Font weight

All the variants used for font weights.

Gap

All the variants of the space tokens. Value 0 is used for no gap.

Margin

All variations of margin combinations and space tokens. Value 0 is used for no margin.

Padding

All variations of padding combinations and space tokens. Value 0 is used for no padding.

Stack

Like the stack layout the stack utility classes add space between vertical elements by adding margin to the top of all but the first element.

The stack utility classes make it easy to space elements based on the space tokens. As the stack works on immediate children only, stack utility classes can be nested.

Visibility

The visually-hidden class hides content visually in the UI, but leaves it accessible to screen readers.

There is no utility class in SmoothCSS to set display: none;. To hide and display content use the hidden attribute instead.

position: absolute;
clip: rect(0 0 0 0);
clip-path: inset(50%);
height: 1px;
width: 1px;
overflow: hidden;
white-space: nowrap;

Wrapper

The wrapper utility classes make it easy to add a wrapper layout of a specific container size. Like the wrapper layout, the content will be the width of the container (padding and border are outside the container width).

The utility classes can be used on their own – you don't need to add the generic wrapper class.