SmoothCSS
  • Introduction
  • Design tokens
  • Global styles
  • Layouts
  • Styling skins
  • Utility classes
  • Customisation

SmoothCSS is in active development

As a result, this documentation and the underlying code will change before a stable release.

Layouts

In general, the size of content is determined by either:

  • The size of the content
  • The size of the content's container

Instead of applying sizes directly to content or individual content containers, SmoothCSS uses layouts to let the browser know how content containers should be displayed relative to each other. And as the layouts are flexible and fluid, they adapt to the space available in their own container (without breakpoints).

The layouts below work on both the marco and micro level. From adding a sidebar to the page, to adding space between a row of buttons.

It can be a little hard to grasp at first, but the extra detail below will help you understand what each layout does and how it can be used. And the examples can be resized to see how the layouts change with the size of their container (the examples work better on larger screens).

You should also be aware there is one exception to the rule of not applying sizes directly to content in SmoothCSS. In the design tokens there are limits to the length of text to ensure it is comfortable to read. These lengths are implemented in the global styles and can be changed or overridden.

Center

The center class horizontally and vertically centers the child element (or elements). The default adds no gap between the child elements. A utility class can be used to add gap when needed.

HTML structure 
<ul class="center" role="list">
  <li>Item 1</li>
</ul>
  • Item 1

Cluster

The cluster class groups items together, and adds uniform spacing between each item. When there isn't enough space for all the items they wrap onto a new row.

HTML structure 
<ul class="cluster" role="list">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>
  • Item 1
  • Item 2
  • Item 3

Custom properties

The following custom properties can be used to adjust the default layout:

  • --cluster-horizontal-alignment: "start", "center" or "end" (default "start").
  • --cluster-vertical-alignment: "start", "center", "end" or "stretch" (default "center").
  • --cluster-gap: the space between each item (both vertically and horizontally).

Grid Auto

The grid-auto class creates a grid of equally sized columns, one for each child element. These columns wrap onto new rows when there isn't enough space to display them in a single row.

HTML structure 
<ul class="grid-auto" role="list">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>
  • Item 1
  • Item 2
  • Item 3

Custom properties

The following custom properties can be used to adjust the default layout:

  • --grid-auto-placement: set to either "auto-fill" or "auto-fit" to change how empty grid tracks are handled.
  • --grid-auto-target-size: the target width of each column before it wraps to a new row. When the columns wrap they will maintain this target width.
  • --grid-auto-min-column-width: the minimum width of each column before it wraps to a new row. When the columns wrap they will extend to 100% of the container width.
  • --grid-auto-gap: the space between each item (both vertically and horizontally).

Prose

The prose class adds spacing between elements used for articles and other prose so they are easier to read (this page, and the rest of the documentation, uses the prose class).

As styles are applied to the HTML elements in the global styles, the prose class only affects the layout. Like the stack layout, it works on immediate children only. But unlike the stack layout the amount of space varies depending on the HTML element.

Custom properties

The following custom properties can be used to adjust the default layout:

  • --prose-space: the space above each element, excluding the first-child (default --space-5).

Region

The region class adds consistent block padding for page sections.

The purpose of the region is to keep layouts consistent. If you need to add padding above and below elements in one or two places it is better to use a padding-block utility class.

HTML structure 
<ul class="region" role="list">
  <li>Item 1</li>
</ul>
  • Item 1

Custom properties

The following custom properties can be used to adjust the default layout:

  • --region-space: the padding added above and below the region.

Repel

The repel class pushes two items away from each other when there is space. When there isn't enough space they stack.

HTML structure 
<ul class="repel" role="list">
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
  • Item 1
  • Item 2

Custom properties

The following custom properties can be used to adjust the default layout:

  • --repel-vertical-alignment: "start", "center", "end" or "stretch" (default "center").
  • --repel-gap: the space between each item (both vertically and horizontally).

Stack

The stack class adds space between vertical elements by adding margin to the top of all but the first element. Works on immediate children only.

HTML structure 
<ul class="stack" role="list">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>
  • Item 1
  • Item 2
  • Item 3

Custom properties

The following custom properties can be used to adjust the default layout:

  • --stack-space: the space between each element (default 1em).

Switcher

The switcher class lays three items next to each other. When there's not enough space for all three items they stack.

Unlike the grid-auto the items do not wrap – they are either in a single row or a single column.

HTML structure 
<ul class="switcher" role="list">
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>
  • Item 1
  • Item 2
  • Item 3

Custom properties

The following custom properties can be used to adjust the default layout:

  • --switcher-size: the minimum width of the container when the items are in a single row. Below this value the items will be in a single column.
  • --switcher-vertical-alignment: "start", "center", "end" or "stretch" (default "start").
  • --switcher-gap: the space between each item (both vertically and horizontally).

Uneven split

Splits the space into two sections: a flexible main content area, and another with a "fixed" width. When there is not enough viewport space to fit both sections they stack.

The uneven-split class has the "fixed" column first – uneven-split-end class has the flexible section first.

HTML structure 
<ul class="uneven-split" role="list">
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
  • Item 1
  • Item 2

Custom properties

The following custom properties can be used to adjust the default layout:

  • --uneven-split-fixed-width: the width of the "fixed" section.
  • --uneven-split-min-main-width: the minimimum size of the flexible section when in a single row (default 50%). Below this value the items will stack.
  • --uneven-split-gap: the space between each item (both vertically and horizontally).

Wrapper

The wrapper class:

  • Add spacing to either side of the content so it doesn't push against the side of its container (or the viewport).
  • Allow the content to reach a maximum width.
  • Center the content when the container is wider than the content and the spacing on either side.
HTML structure 
<ul class="wrapper" role="list">
  <li>Item 1</li>
</ul>
  • Item 1

Custom properties

The following custom properties can be used to adjust the default layout:

  • --wrapper-max-inline-size: the maximum width of the content (the padding and border are not included in this value).
  • --wrapper-buffer: the space between the container and either side of the content.