Utilities

What they are for

Brio is not a utility-first library, but that doesn't mean they aren't useful. To me, utilities are super useful when they encapsulate common patterns or can alter the behavior of something, such as a composition. It should be considered a one-off override that is so useful it would be a crime not to have it readily available, such as altering the --flow-space of the .flow composition. Utilities are higher in the layer stack, above components, so they win by layer order without !important.

So, there are a few utilities added with restraint. When a utility starts appearing in the same shape in several places, that shape wants to be a component or a scoped custom property, not a utility you paste everywhere. The tables below are generated straight from src/css/utilities.css.

Text

Alignment, color, size, weight, family, and line height. The size and leading classes key to the same fluid scales the type tokens define, so they move with the viewport the way the rest of the system does. The wrapping classes set text-wrap: balance evens out line lengths in short text, pretty keeps widows and orphans out of paragraphs.

Alignment

Logical-property values so RTL writing modes flip correctly.

Color

Maps to semantic color tokens. Keep these minimal; component-scoped tokens are usually the right override point instead. (The color reset is .text-default, not .text-normal -- that name belongs to the weight group below and the pair once collided.)

Family and case

Size

Keyed to the fluid type scale. See the type scale on the Tokens page for the resolved sizes at each breakpoint.

Weight

Line height

Text wrapping

CSS provides two modes with different jobs. balance evens out line lengths in short text; pretty pushes widows and orphans out of paragraphs. The degrade gracefully, as unsupported browsers will simply ignore the declarations.

Link decorations

These utilities are for decorating links and changing default link styles.

Spacing

The .gap-* classes set the gap property directly, keyed to the raw --space-* scale. That reaches any gap-driven container, the compositions included: gap does not inherit, and the utilities cascade layer wins over the composition layer, so .stack.gap-xs or .cluster.gap-2xl restyles that one element at any step. The .is-snug and .is-tight variants are the tier-named shortcuts for the common density shifts; remapping the primitive's own gap custom property to a --gutter-* alias keeps the tier vocabulary when you want it.

The .flow-space-* classes do the same for flow rhythm through --flow-space, which can be set on the container or on an individual child.

The .measure-* classes set a reading width in ch for text that isn't prose, such as a paragraph inside a sidebar or a table's intro. The mechanics match .gap-*: element-scoped, and the @utilities layer override the width tokens that prose and center already support.

Gap

Set the gap property directly, keyed to the raw --space-* scale. Works on any gap-driven container, the gap compositions included: the utilities layer wins over the composition layer, and gap does not inherit.

Flow space

Set --flow-space at the --space-* scale. Apply to a .flow container to set its rhythm, or to an individual child to tune the gap above just that element.

Measure

Set max-inline-size to a reading width in ch so the measure tracks the font rather than the viewport. Same mechanics as .gap-*: the utilities layer wins over prose and center, and max-inline-size does not inherit, so the override is scoped to its element. Two steps bracket the 65ch default that .prose and .center already carry; anything narrower or wider is a project call.

Accessibility

Brio tries to be accessible. So, a few helpers have been included to assist with creating more accessible interfaces.

• .visually-hidden removes an element from sight without removing it from the accessibility tree: it clips to a zero-size box instead of using display: none, so screen readers still announce it. Use it for skip links, table captions, and labels that exist for assistive technology only.

Accessibility

Helpers for assistive technology. The comparative prose -- why .visually-hidden over display: none, when to reach for .link-plain -- lives on the utilities page; these rows carry the one-line contract.

Responsive helpers

Container-query opt-in and viewport-based hiding. The container classes keep the response tied to the box that actually changed size, which is usually what a component-level layout wants, while the viewport classes hide chrome at breakpoints. Each .hide-* class also has a .show-* counterpart that names the same behavior from the other side: .show-below-md is visible only below md, the same rule as .hide-above-md. I included both, as some names just seem more intuitive when reading the element's role. For example, an element that appears on small screens is a might be better named as .show-below-md, but an element that leaves might use .hide-below-md. It depends on how you're reading the element's role.

Viewport

Show and hide elements based on viewport width. Breakpoints: sm 40rem, md 48rem, lg 64rem.

Container queries

Opt a parent into container queries with .cq-inline, then use .cq-hide-* and .cq-show-* on its descendants to respond to the container's inline size instead of the viewport.

Container queries demo

<div class="cq-inline flow">
            <p>The box you are resizing is the container these two lines listen to.</p>
            <p class="cq-hide-below-md text-success">The container is narrower than md (48rem).</p>
            <p class="cq-hide-above-md text-danger">The container is md (48rem) or wider.</p>
        </div>

Drag the handle past 48rem and the lines trade places, with no media query and no viewport involved. The breakpoints are the same sm, md, and lg the viewport classes use, matched on purpose; the only difference is what the width resolves against, the container's inline size for .cq-hide-* and the viewport for .hide-*.