Utilities

One hand-written file, 161 classes, every one of them a token with a class name on it. No generator, no config, no scanner, no arbitrary-value syntax and no build step — if a class is here, somebody chose to type it.

What this layer is

src/utilities.css is a single static file. There is nothing that produces it and nothing that consumes it: no JIT engine, no content glob, no class scanner walking your templates, no purge step, and no escape hatch for values the scale does not have. It ships exactly as it is written, and what you read in the file is what lands in the browser.

That has one consequence worth stating plainly. The class list is finite and it is short. There are 161 classes across thirteen groups, and there is no syntax for asking for a hundred and sixty-second. That is not a limitation the file is apologising for — it is the design.

This is not a Tailwind clone and it is not a Bootstrap clone. No class name, scale value, or source from either was used in building it. The names come from the properties they set and the steps come from @arag's own space tokens and type tokens. Where a convention here happens to resemble one elsewhere, it is because both were reading the same CSS specification.

Why every class is prefixed u-

Components are bare. A card is .card, its footer is .card__footer, and there is no prefix anywhere in the component layer. Utilities take the opposite decision and prefix all 161, for two reasons that both pay off at the call site.

The first is that it makes a collision impossible. A component named .flex or .hidden is not far-fetched, and a utility layer that could shadow one would make every future component name a compatibility question. With the prefix, the two namespaces cannot touch.

The second matters more day to day: it makes the markup readable. In class="card u-pad-6" you can see at a glance which token is the thing and which token is the adjustment, without knowing either name in advance.

<!-- component, then adjustments. The prefix does the sorting for you. -->
<article class="card u-pad-6 u-gap-3">
  <h3 class="card__title u-text-lg u-wrap-balance">Дансны үлдэгдэл</h3>
  <p class="u-color-muted u-margin-block-0">Төлбөрийн мэдээлэл амжилттай шинэчлэгдлээ.</p>
</article>

The prefix also means a grep for u- in your templates returns every place the utility layer is load-bearing, which is the audit you actually want to run before changing a token.

Where the layer sits

index.css declares the order once, before anything is imported:

@layer reset, tokens, base, components, utilities, overrides;

utilities comes after components, so a utility beats a component whenever they set the same property — no specificity trick, no repeated selector, nothing raising its own priority. And because your own application CSS is unlayered, it still beats both. The whole override story is layer order, top to bottom, and nothing in this package fights you for a property. The full order and why it is that order →

Below, both cards are .card. The second one carries two utilities that overwrite the padding and background .card sets on itself. Same element, same specificity, one class each — the layer decides.

<article class="card">…</article>
<article class="card u-pad-3 u-bg-sunken">…</article>

/* @layer components */
.card {
  padding: var(--card-padding);          /* --space-6 */
  background-color: var(--card-bg);      /* --color-surface */
}

/* @layer utilities — later layer, so these win */
.u-pad-3     { padding: var(--space-3); }
.u-bg-sunken { background-color: var(--color-surface-sunken); }

Display

Ten classes. Nine set a display keyword; the tenth removes an element visually while leaving it in the accessibility tree.

<span class="u-inline-block u-pad-3 u-bg-sunken u-border-subtle u-radius-sm">…</span>
<span class="u-sr-only" lang="mn">Гуйвуулга баталгаажлаа</span>

Flex

Seventeen classes, all keywords, none of them touching a length. u-flex itself lives in the display group; everything here assumes it or u-inline-flex is already on the element.

start and end rather than flex-start and flex-end: the logical keywords follow the writing direction, which is the same rule the rest of the package holds to. There is no u-items-* or u-justify-* for left or right, and there will not be.

<div class="u-flex u-flex-wrap u-items-center u-justify-between u-gap-4
            u-pad-4 u-bg-sunken u-border-subtle u-radius-md">
  <strong lang="mn">Дансны үлдэгдэл</strong>
  <span class="u-numeric u-weight-semibold">1,284,500.00</span>
</div>

Grid

Eight classes. Two of them reflow on their own and are the ones to reach for; three are fixed column counts that do not.

The min(token, 100%) inside the minmax() is what keeps u-grid-auto and u-grid-cards from overflowing a phone: at 375px the column floor collapses to the container width instead of holding at 16rem. Neither needs a media query, because the columns answer to the content's own minimum.

The fixed counts do not do that. At 375px, u-grid-2 is still two columns and a Cyrillic label a fifth longer than its English source is the first thing to overflow. Use them where the count is the point — a pair of side-by-side charts, a four-up legend — and reach for u-grid-auto everywhere else.

<div class="u-grid u-grid-auto u-gap-4">
  <div class="u-pad-4 u-bg-sunken u-border-subtle u-radius-md" lang="mn">Шинэ захиалга үүсгэх</div>
  …
</div>

Narrow this window and those three cells become two, then one, on their own.

Gap

Ten classes, one per space step, and nothing else. gap gets the full scale because it is the one spacing mechanism that never collapses and never needs a last-child exception.

One class sets both axes. There is no row-gap or column-gap utility, because a grid that wants them different is a layout with an opinion, and that belongs in your own CSS.

<div class="u-flex u-flex-wrap u-gap-1">…</div>
<div class="u-flex u-flex-wrap u-gap-5">…</div>
<div class="u-flex u-flex-wrap u-gap-8">…</div>

Padding

Thirty classes: three axes × ten steps. The pattern is the whole table, so here is the pattern rather than thirty near-identical rows.

The axes are logical: inline is the axis the text runs along and block is the one it stacks along, whatever the writing mode. There is no u-pad-left and there is no single-side padding utility at all — padding one edge is a component decision, not a spacing adjustment.

<div class="u-bg-sunken u-border-subtle u-radius-md u-pad-2">…</div>
<div class="u-bg-sunken u-border-subtle u-radius-md u-pad-6">…</div>
<div class="u-bg-sunken u-border-subtle u-radius-md u-pad-inline-9 u-pad-block-2">…</div>

Margin

Sixteen classes, and the shape is deliberately lopsided: the block axis gets the whole scale, the inline axis gets 0 and auto and nothing else. That asymmetry is one of the deliberate omissions, and it is the one most likely to look like an oversight.

The three single-edge classes are all zeroes and one auto, because that is what a margin utility is actually needed for in practice: cancelling the rhythm base.css puts on a paragraph or a heading, and pinning a footer. Adding a positive value to one block edge is a rhythm decision, and rhythm belongs to the component.

<p class="u-margin-block-0">…</p>
<p class="u-margin-block-0 u-color-muted u-text-sm">Flush.</p>

Type

Twenty-seven classes across six sub-groups: size, leading, weight, tracking, family, alignment, plus the numeric and wrapping helpers. Every one hands through a token from the type scale.

u-text-start and u-text-end, never left and right. The alignment follows the writing direction the same way the padding axes do.

<p class="u-text-2xl u-weight-bold u-wrap-balance" lang="mn">Шинэ захиалга үүсгэх</p>
<p class="u-text-lg u-weight-medium" lang="mn">Хэрэглэгчийн тохиргоо</p>
<p class="u-text-sm u-color-muted u-tracking-wide" lang="mn">Утасны дугаар</p>
<p class="u-text-xs u-font-mono u-numeric">1,284,500.00 · 0.00 · 118,000.25</p>

Text colour

Eight classes, all semantic roles. There is no utility for a raw ramp step — that omission has its own entry.

Every one of those re-resolves in dark mode without the class changing. That is the entire argument for keeping the colour utilities semantic. How the roles switch →

Background

Ten classes. Five surface roles, four family fills, and transparent.

<span class="u-pad-4 u-radius-md u-bg-brand u-color-brand u-text-sm">…</span>
<span class="u-pad-4 u-radius-md u-bg-danger u-color-danger u-text-sm">…</span>

Border

Six classes. Three all-round weights at the three border colour roles, one canceller, and two single-edge rules that turn up constantly in real layouts.

u-border-none sets a zero-width transparent border rather than border: none, so an element that gets it keeps its box model unchanged and can be given a border back on hover or focus without the layout jumping by a pixel.

<div class="u-pad-4 u-border u-radius-md">…</div>
<div class="u-pad-4 u-border-inline-start" lang="mn">Гуйвуулга баталгаажлаа</div>

Radius

Six classes, one per radius token, minus --radius-xs and --radius-2xl — those two exist in tokens.css for components to reach for and have never been wanted as a one-off adjustment.

<span class="u-inline-block u-pad-4 u-bg-sunken u-border-subtle u-radius-full">full</span>

Shadow

Five classes, one per elevation token. --shadow-xl is not exposed as a utility: the top of the shadow scale belongs to overlays, and an overlay is always a component.

<div class="u-pad-5 u-bg-raised u-radius-lg u-shadow-md">u-shadow-md</div>

Elevation in this system is asymmetric between themes — in dark mode a raised surface lightens as well as casting a shadow, because a shadow on a dark ground is nearly invisible. That is why u-bg-raised and a shadow utility are usually applied together. Why elevation is asymmetric →

Size

Eight classes. Six are maximums, one is a full width, one is a scroll container. There is no fixed-width utility in the file — that omission has its own entry.

Pair a container class with u-margin-inline-auto to centre a column, which is the one place an inline margin is unambiguously right.

<div class="u-scroll-inline u-border-subtle u-radius-md u-pad-3">
  <div class="u-flex u-flex-nowrap u-gap-4">
    <span class="u-flex-none u-pad-4 u-bg-sunken u-radius-sm" lang="mn">Шинэ захиалга үүсгэх</span>
    …
  </div>
</div>

The deliberate omissions

Four things a utility layer is normally expected to have and this one does not. None of them is an oversight, and each one is the direct consequence of a rule the system holds elsewhere. If you came here looking for a class and did not find it, this is almost certainly the section that explains why.

No truncation utility of any kind

There is no text-overflow utility, no line clamp, no white-space: nowrap. Not a shorter list than usual — none at all.

The reason is grammatical, not aesthetic. Mongolian Cyrillic is agglutinative: the case suffix at the end of a word is what tells you whether the word is the subject, the object, the destination or the possessor. An ellipsis eats the end of the string, which is exactly where that information lives. Truncating English costs you some words. Truncating Mongolian can leave a grammatically incoherent fragment that means something other than the original, and the reader has no way to tell which.

So the layer does not offer a one-class shortcut to it. The sanctioned answers are u-wrap-balance for a heading, u-wrap-pretty for body copy, and u-wrap-anywhere for an unbroken token such as a wallet address or a transaction reference. All three let the text be fully present; they only argue about where the line breaks.

Both panels are the same string at the same ceiling. The left one grows a second line and stays readable. The right one keeps its single line by throwing away the verb ending — the part that says the update succeeded. The clipping rule on the right is a docs-only rule written for this comparison; it is not in utilities.css and it is not going to be.

No fixed-width utility

The size group offers maximums and one relative full width. There is no inline-size utility at a fixed length, and no plan for one.

A fixed inline size is the single most reliable way to clip a Cyrillic label, because it makes the decision before the text exists. A maximum does not: a box with max-inline-size is free to be narrower when the content is short and is capped only when the content is long, which is a ceiling on the layout rather than an assumption about the string. u-full is relative and therefore cannot clip anything either — it resolves against whatever the parent turns out to be.

The same rule runs through the rest of the package: --size-touch and --size-control are applied as min-block-size and never as a height, so a button that needs two lines gets two lines. The floors, not heights, rule →

Inline margins get only 0 and auto

The block axis gets all ten space steps. The inline axis gets u-margin-inline-0 and u-margin-inline-auto, and that is the entire inline margin surface.

An inline margin on a text-bearing element is how a layout starts assuming a width. Once something is indented by a fixed amount on the side the text runs along, the space left for the text is a fixed subtraction from the container — and that subtraction was almost always sized against the English draft. It is the same assumption a fixed width makes, arrived at from the other direction, and it is exactly the assumption the bilingual rule forbids.

auto is exempt because it is not an assumption about a width: it is an instruction to divide whatever space is left, equally, in both directions. That is centring, and centring is fine.

<div class="u-container-sm u-margin-inline-auto u-pad-5
            u-bg-sunken u-border-subtle u-radius-md u-text-center">
  <span lang="mn">Хэрэглэгчийн тохиргоо</span>
</div>

No raw-ramp colour utilities

u-color-brand-600 does not exist. Neither does u-bg-neutral-200 or any of the other 60-odd classes a ramp-per-step generator would produce.

A ramp step is an absolute colour. --color-brand-600 is the same colour in light mode and in dark mode, by design — that is what makes it useful as a raw material for building the semantic roles out of. Handed a class name, though, it stops being raw material and becomes a light-mode-only class: readable on the light ground it was chosen against, and unreadable the moment the theme flips.

The eight text colour and ten background utilities all point at semantic roles instead, and every one of them re-resolves when the theme changes without the markup moving. That is the whole reason the role layer exists, and exposing the ramp directly through a utility would route around it. The roles and what they are for →

Living with the layer

The [hidden] guard

The file ends with a block that restates every display-setting utility with [hidden] attached. It is eight selectors and one declaration, and it fixes a bug that shipped in nine of the ten component files before anybody caught it.

The trap: reset.css contains [hidden] { display: none }, which is what makes the HTML hidden attribute work. But reset is the first layer. Anything that sets display in a later layer beats it, silently, and the element stays visible while the accessibility tree has already been told it is gone.

Here it is worse than in the component files, because utilities sits one layer higher still. <div class="u-flex" hidden> would have beaten reset.css and any component's own guard.

/* The last block in utilities.css. */
.u-block[hidden],
.u-inline[hidden],
.u-inline-block[hidden],
.u-flex[hidden],
.u-inline-flex[hidden],
.u-grid[hidden],
.u-inline-grid[hidden],
.u-contents[hidden] {
  display: none;
}

u-hidden needs no entry — it already sets display: none, so there is nothing for the attribute to lose to. And this is the reason to prefer the hidden attribute over u-hidden for anything that toggles: the attribute is one property in the DOM that both the renderer and the screen reader agree on, where a class is a second source of truth that can drift out of sync with the aria- state beside it.

<div class="u-flex u-gap-4 …">…</div>
<div class="u-flex u-gap-4 …" hidden>…</div>  <!-- stays gone -->

When not to reach for a utility

Two honest cases, and neither is a failure of the layer.

You are writing the same three utilities on every instance. If every card in your product carries u-pad-4 u-bg-sunken u-radius-md, that is not three adjustments — that is a component with a name nobody has written down yet. Write the class, put the three declarations in it, and the next person gets the decision instead of having to re-derive it. A utility repeated across a codebase is a component in denial, and it is the kind of duplication that goes stale one instance at a time.

You need a value the scale does not have. There is no arbitrary-value syntax and there is not going to be one. Write the rule in your own CSS. It is unlayered, it sits above all six of the system's layers, and it wins by existing — no !important, no specificity fight, no override file. That is not a workaround; it is the documented override mechanism. Why unlayered code wins →

What both cases have in common is that the answer is to write CSS, not to make the utility layer bigger. The layer is 161 classes because 161 decisions were made. Every class added without a decision behind it makes the other 161 harder to find.