Utilities

Utilities handle the cases that don't earn their own component or token override: set text alignment on one element, nudge a gap to a specific size, hide something on mobile. Each utility does exactly one thing. They live in the utilities cascade layer, so they win over lower layers without !important.

Brio is not a utility framework. The catalog below is deliberately narrow and will stay that way: if you find yourself wanting more, first check whether a token override, composition primitive, or component handles it. Only reach for a utility when those don't.

The class tables below are pulled from src/css/utilities.css via brio cssref, so they stay in sync with the source. The two single-utility sections (.visually-hidden and .link-plain) are described in prose because their behavior doesn't fit a one-line table cell.

Visibility

• .visually-hidden -- hide from the visual UI while remaining in the accessibility tree. Use for skip links, form labels that the design doesn't show, and screen-reader-only text. Not the same as [hidden] (which removes the element from the a11y tree too).

Text

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.

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.

See Tokens -- Type scale for the resolved sizes at each breakpoint.

Weight

Line height

Links

• .link-plain -- remove underline and use --color-text. For logo links, breadcrumb home, and similar cases where the anchor is chrome rather than prose.

Spacing

Gap

Set the gap property directly, keyed to the raw --space-* scale. Use when you want an explicit size on a flex or grid container.

For density-aligned gaps (inside .stack, .cluster, or a component), prefer the .is-snug / .is-tight modifiers the composition primitive provides, or override --stack-gap / --cluster-gap with a --gap-* alias from the density grammar. The raw .gap-* utilities are for deliberate one-off sizing.

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.

Apply .flow-space-* to a .flow container to set its rhythm, or to an individual child to tune the gap above just that element (see the Flow per-child override pattern).

Responsive visibility

Viewport

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

Breakpoints match the breakpoints reference. Pair them for mobile-swap-desktop patterns: .hide-above-md on the hamburger button, .hide-below-md on the nav. The hamburger shows below the breakpoint; the nav shows at and above.

Container queries

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

Use container queries when you want responsive behavior based on a container's width instead of the viewport -- useful for widgets that appear in contexts of varying width (sidebar vs main, card grid vs full width, etc.).

Drag the right edge to cross the md breakpoint and see the utilities swap:

<docs-resize>
    <div class="cq-inline">
        <p>This is a query container.</p>
        <p class="cq-hide-below-md text-success">I hide when the container is under 48rem (md).</p>
        <p class="cq-hide-above-md text-danger">I hide when the container is 48rem or wider.</p>
    </div>
</docs-resize>

Container-query breakpoints match the viewport breakpoints so the vocabulary stays consistent. The difference is what the breakpoint resolves against -- the container's width for .cq-*, the viewport for .hide-*.