Composition

Brio is built with the idea of composition in mind. This comes from both the Cube CSS methodology and the Every Layout book. The ideas a little abstract, but once you get the hang of it, you'll see how efficient it can be to build any layout using a small set of primitive classes. A primitive is a class that solves one recurring layout problem and nothing else. For example, .stack is used for vertical layout, .cluster is used for a wrappable horizontal row, .grid is used for autofill columns.

The primitives are meant for layout-only. So, they don't define colors, borders, or backgrounds. This makes them more usable with themed components. Some components I called themed veneers. These are often rows that are composed with primitives. For example, an alert component is composed with a .media composition, a navbar uses a .cluster.is-between composition. This allows for a separation of concerns between layout and styling, and means we can use a smaller set of CSS classes to build out multiple layouts.

As mentioned, the vocabulary comes from Every Layout, Heydon Pickering and Andy Bell's catalogue of composable layout patterns. You should buy their book, it's worth the cost, and it helps support their work. Most of the primitives below are Brio's implementations of their named layouts: flow is their lobotomized owl, stack, cluster, grid, switcher, reel, frame, cover, center, and media all have counterparts there, and flank follows their sidebar. The argument behind the whole approach is that layout should be a small vocabulary of reusable patterns rather than a pile of one-off rules.

Tuning with scoped tokens

Each primitive exposes a a set of knobs as scoped custom properties, such as --stack-gap, --grid-min, and --switcher-threshold. These are used only by that class. This approach allows you alter the behavior of a composition by setting them on the instance (or a wrapper) to tune that one piece without touching anything else:

<div class="grid" style="--grid-min: 8rem">...</div>

There are three rules of thumb. First, if the primitive's default fits your need, don't add anything else. Second, use the modifier classes (.is-snug, .is-reversed, .is-between) before you write a custom property. Third, if you can't find a modifier that fits, just use the style attribute or create your own modifiers in CSS. For this library, it is not a crime to use the style attribute or create your own modifiers in CSS. That's how CSS is meant to be used.

The Compositions

Each of the compositions has its own page under Composition in the sidebar. Please see those pages for details.

Most compositions come with some helper classes and tokens. However, Brio isn't meant to be a complete framework. So, only the most common helpers were added. If you need more, just add your own modifiers in your project's CSS.