Utilities

The utility classes behind the elements: token colours, radius, breakpoints and sizes, with the usual layout and spacing classes.

Updated
On this page

Utilities are single-purpose classes for the one-off look: a margin, a colour, a grid. They come from UnoCSS, through the Wind preset the ui preset builds on, so the names are the familiar ones (flex, gap-4, p-3, text-sm, grid-cols-2, hidden). The preset changes only what ties them to the UI: colours, radius and breakpoints read the tokens, and a surface fill brings its text colour.

Only what you use is built

The build scans the templates it is given and writes a rule for each class it finds, so the stylesheet holds only what the site uses. A class assembled in a template from pieces, like 'bg-' ~ $color, is never found. Write the whole name, or list the full names a template can produce.

Beating an element

The reset, the base and the element CSS sit in a layer before the utilities, and every element rule is written with :where(). A utility on an element therefore beats the element's own rule at the same specificity, with no !important:

{ui card, class: 'max-w-sm' /}
{ui button, title: 'Wide', class: 'w-full' /}

Colours

Every token is a colour. The fill is bg-{name}, text-{name}, border-{name} and the rest of the colour utilities. A pair names the text that sits on its fill, and bg-primary sets text-primary-contrast for you (bg-well sets text-ink). A text-* class on the same element still wins. Because the tokens change with the theme, a utility written with them follows light, dark and any added theme, and there is no dark: variant to write.

Token colours

primary
raised
sunken
hover
muted
destructive
border

<div class="flex flex-wrap gap-2">
	<div class="rounded-md bg-primary px-3 py-2 text-sm text-primary-contrast">primary</div>
	<div class="rounded-md bg-card px-3 py-2 text-sm text-ink">raised</div>
	<div class="rounded-md bg-well px-3 py-2 text-sm text-ink">sunken</div>
	<div class="rounded-md bg-hover px-3 py-2 text-sm text-ink">hover</div>
	<div class="rounded-md px-3 py-2 text-sm text-muted">muted</div>
	<div class="rounded-md bg-destructive px-3 py-2 text-sm text-destructive-contrast">destructive</div>
	<div class="rounded-md border px-3 py-2 text-sm">border</div>
</div>

The names are canvas, ink, card, primary, secondary, muted, accent, destructive, success, warning and info, each with a -contrast pair, plus border, input and ring. Theming shows them live.

Alpha

A slash sets the opacity of any colour utility. It is the way to get a soft tint from a status colour.

Alpha

bg-primary/10
bg-success/15
bg-warning/15
bg-info/15
bg-destructive/15

<div class="flex flex-wrap gap-2">
	<div class="rounded-md bg-primary/10 px-3 py-2 text-sm text-primary">bg-primary/10</div>
	<div class="rounded-md bg-success/15 px-3 py-2 text-sm text-success">bg-success/15</div>
	<div class="rounded-md bg-warning/15 px-3 py-2 text-sm text-warning">bg-warning/15</div>
	<div class="rounded-md bg-info/15 px-3 py-2 text-sm text-info">bg-info/15</div>
	<div class="rounded-md bg-destructive/15 px-3 py-2 text-sm text-destructive">bg-destructive/15</div>
</div>

Radius

rounded-lg is --radius, rounded-md is 2px less and rounded-sm is 4px less. Changing --radius in a theme moves all three, and every element that rounds with the token. rounded-full and rounded-none stay fixed.

Radius

rounded-sm
rounded-md
rounded-lg
rounded-full

<div class="flex flex-wrap gap-2">
	<div class="border px-3 py-2 text-sm rounded-sm">rounded-sm</div>
	<div class="border px-3 py-2 text-sm rounded-md">rounded-md</div>
	<div class="border px-3 py-2 text-sm rounded-lg">rounded-lg</div>
	<div class="border px-3 py-2 text-sm rounded-full">rounded-full</div>
</div>

Breakpoints

A prefix applies a utility from that width up: sm:grid-cols-2 is two columns at 640px and wider. One scale serves every prefix, and xxl takes the place of 2xl.

Prefix From
xs: 480px
sm: 640px
md: 768px
lg: 1024px
xl: 1280px
xxl: 1536px

Start with the layout for the smallest screen and add prefixes as the space grows.

Columns by breakpoint

One column
Two from sm
Four from lg
Resize the window

<div class="grid grid-cols-1 gap-2 sm:grid-cols-2 lg:grid-cols-4">
	<div class="rounded-md bg-well p-3 text-sm">One column</div>
	<div class="rounded-md bg-well p-3 text-sm">Two from sm</div>
	<div class="rounded-md bg-well p-3 text-sm">Four from lg</div>
	<div class="rounded-md bg-well p-3 text-sm">Resize the window</div>
</div>

Stack and row

Two classes of the ui sheet, not utilities, cover the most common flex layouts. .stack is a column and .row is a row with its items centred. Both take their gap from data-gap, a step of 1, 2, 3, 4, 6 or 8 (0.25rem to 2rem, the same sizes as gap-1 to gap-8). Without it the gap is 0. They work on any tag, so a list can be <ul class="stack" data-gap="2">.

They sit at the same level as an element's own rules, so a utility still beats them: flex-wrap lets a row wrap, items-start aligns it to the top, gap-12 sets a gap off the scale and lg:flex-row turns a stack into a row from 1024px.

Stack and row

Project Active
Updated today

<div
	class="stack rounded-lg border p-4"
	data-gap="4"
>
	<div
		class="row"
		data-gap="2"
	>
		<span class="font-semibold">Project</span>
		{ui badge, title: 'Active' /}
	</div>
	<span class="text-muted">Updated today</span>
	<div
		class="row flex-wrap"
		data-gap="2"
	>
		{ui button, title: 'Open' /}
		{ui button, title: 'Share', class: 'button-outline' /}
	</div>
</div>

Layout and spacing

The rest are the standard utilities. A flex or grid container with a gap lays out its children, and elements nest inside them like any other tag.

Flex and gap

Project Updated today
Active

<div class="flex items-center justify-between gap-4 rounded-lg border p-4">
	<div class="flex flex-col gap-1">
		<span class="font-semibold">Project</span>
		<span class="text-sm text-muted">Updated today</span>
	</div>
	<div class="flex gap-2">
		{ui badge, title: 'Active' /}
		{ui button, title: 'Open', class: 'button-outline' /}
	</div>
</div>

Tags carry no margin of their own, so space between blocks comes from a gap on the container, or from .prose for running text.

Sizing elements

Elements are measured in em, so the text size classes (text-xs, text-sm, text-base, text-lg, text-xl) size them: text-lg on a button makes the box, the padding and the icon larger, and md:text-lg does it from 768px. A modal's width is not text-relative, so it has two classes, modal-sm and modal-lg. The overview covers size, colour and looks.

Prose

.prose is a class of its own, like .stack and .row. Put it on a container of rendered markdown. It spaces and styles only the container's direct children, so a component placed among them keeps its own look:

<div class="prose">
	{$html|noescape}
	{ui alert, title: 'Heads up' /}
</div>