RamosLabs DS

Foundations / Helpers

One class. One job. Straight from a token.

Utilities are the stagehands of the system: small, single-purpose classes that do exactly one thing and take no bow. One aligns a row, one spaces two cards, one hides a label from sight while keeping it for a screen reader. This is a curated set, not a dump, and every value traces back to a token. If a helper would type 16px by hand instead of reading --space-4, it does not belong here.

01

Token, utility, or component

Three layers carry style, and choosing the right one is most of the craft. Reach for the layer that answers the question you actually have.

Layer 1
Token
The value, named once. --space-4, --color-primary, --radius-lg. Everything else points back here.
What is the value?
Layer 2
Utility
One class, one declaration, sourced from a token. .gap-4 sets gap: var(--space-4). A quick, local fix in markup.
Apply one value, here, now.
Layer 3
Component
A named pattern with scoped styles, structure, and states. An event card, a button, a checkout row. The main act.
A whole reusable thing.
RuleSource every utility value from a token, never a hand-typed value.
WhyThat is what separates a design-system utility from a loose grab bag of CSS. Every helper is a thin, named shortcut to a decision the tokens already made.
Recommended
.gap-4 { gap: var(--space-4); }Reads the token, so one change to the scale updates every gap at once.
Avoid
.gap-4 { gap: 16px; }A hand-typed pixel drifts from the token and quietly breaks the system.
02

The catalog

Every class below is one declaration, and every sized value traces to a token. These stay in markup so you read the layout at a glance.

Display

ClassDeclaration
.d-nonedisplay: none
.d-blockdisplay: block
.d-inlinedisplay: inline
.d-inline-blockdisplay: inline-block
.d-flexdisplay: flex
.d-inline-flexdisplay: inline-flex
.d-griddisplay: grid

Flexbox

ClassDeclaration
.flex-rowflex-direction: row
.flex-colflex-direction: column
.flex-wrapflex-wrap: wrap
.flex-1flex: 1 1 0%
.flex-autoflex: 1 1 auto
.flex-noneflex: none

Alignment

ClassDeclaration
.items-startalign-items: flex-start
.items-centeralign-items: center
.items-endalign-items: flex-end
.justify-centerjustify-content: center
.justify-betweenjustify-content: space-between
.justify-endjustify-content: flex-end

Layout & overflow

ClassWhat it does
.w-fullwidth: 100%
.h-fullheight: 100%
.min-w-0Lets a flex child shrink so truncation works.
.overflow-autooverflow: auto
.truncateOne line, ellipsis: hidden overflow, nowrap, ellipsis, together.

Gap (every step is a token)

ClassTokenValue
.gap-1var(--space-1)0.25rem
.gap-2var(--space-2)0.5rem
.gap-3var(--space-3)0.75rem
.gap-4var(--space-4)1rem
.gap-6var(--space-6)1.5rem
.gap-8var(--space-8)2rem

Typography

ClassToken or property
.text-centertext-align: center
.text-smvar(--font-size-sm)
.text-basevar(--font-size-base)
.text-lgvar(--font-size-lg)
.text-xlvar(--font-size-xl)
.font-mediumvar(--font-weight-medium)
.font-semiboldvar(--font-weight-semibold)
.font-boldvar(--font-weight-bold)

Text color (semantic tokens only)

ClassToken
.text-primaryvar(--color-text-heading)
.text-secondaryvar(--color-text-secondary)
.text-mutedvar(--color-text-muted)
.text-errorvar(--color-error-text)
.text-successvar(--color-success-text)

Border radius

ClassTokenValue
.rounded-smvar(--radius-sm)0.375rem
.rounded-mdvar(--radius-md)0.5rem
.rounded-lgvar(--radius-lg)0.75rem
.rounded-xlvar(--radius-xl)1rem
.rounded-pillvar(--radius-pill)9999px
RuleName each helper after the token it reads, so one vocabulary runs top to bottom.
WhyA class named for a value the token layer never uses is exactly the drift that erodes trust in the system.
Recommended
.rounded-pill → var(--radius-pill)The class mirrors the token name, so the two always stay in sync.
Avoid
.rounded-fullDescribes a scale the tokens never define; the mismatch invites drift.
03

Utilities at work

A handful of structural helpers, read in one glance. This is fair use. The moment the same cluster becomes a card you build twenty times, give it a name and let the helpers go.

HTML
<!-- Ticket status: label left, state right, one token gap -->
<div class="d-flex items-center justify-between gap-4">
    <span class="text-muted text-sm">Ticket status</span>
    <span class="font-semibold text-success">Confirmed</span>
</div>

<!-- Long venue name that must never break the row -->
<div class="d-flex items-center gap-2 min-w-0">
    <span class="truncate">Teatro Metropolitano Jose Gutierrez Gomez</span>
</div>

<!-- Icon-only button: eyes see the X, screen readers hear the label -->
<button class="d-inline-flex items-center focus-ring cursor-pointer">
    <span class="sr-only">Close ticket details</span>
    <svg aria-hidden="true">...</svg>
</button>
04

The two helpers that matter most

Two exist purely to serve assistive technology. Treat them as required infrastructure, not decoration.

ClassPurpose
.sr-onlyVisually hidden, still announced by screen readers. For icon-button labels, form hints, and status that is obvious by sight but silent to the tree.
.focus-ringApplies the system focus treatment on :focus-visible, pairing with var(--color-focus) so keyboard users always see where they are.
Inside .sr-only, declaration by declaration

Visually hidden is a solved problem with a canonical recipe. The common shortcut of display: none is wrong for it: that also drops the element from the accessibility tree, the opposite of the goal. This hides the pixels while keeping the text for a screen reader.

position: absolute

Pulls the element out of flow so its collapsed box disturbs nothing around it.

width: 1px; height: 1px

Collapses the box to one pixel. Not zero, since a zero-sized box can be dropped from the tree.

overflow: hidden

Clips the real content down to that one-pixel box so none of it paints.

clip + clip-path: inset(50%)

Clips the visible region to nothing. The clip-path rule does the work in modern engines; the deprecated clip stays as a fallback.

white-space: nowrap

Stops the collapsed text from wrapping, which could reintroduce a sliver of layout.

margin: -1px; border: 0

Zeroes the box model and nudges it off-screen so nothing leaks, not a border, not a background.

CSS
/* The canonical visually-hidden utility */
.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    clip-path: inset(50%);
    white-space: nowrap;
    border: 0;
}
RuleUse .sr-only for meaning that is obvious by sight but silent to the tree, never to stuff invisible keywords.
WhyThe word behind an icon-only button, the meaning of a required asterisk. A skip link that must reveal itself on keyboard focus uses the focusable variant. See Patterns / Accessibility.
Recommended
<span class="sr-only">Close</span>Keeps the pixels hidden while the label still reaches assistive tech.
Avoid
display: noneDrops the element from the accessibility tree, so a screen reader never hears it.
05

Which layer, in five questions

When you are unsure which tool to reach for, walk down until one fits.

Just need the value, inside a component's own scoped CSS? Reference the token, for example var(--space-4). No utility needed.
One structural adjustment in markup, a gap, an alignment, a width? Use the matching utility.
The same three or four utilities always travel together on the same kind of element? That pattern has a name. Extract a component.
The element needs structure, states, or behavior, a card, a modal, a checkout row? Build it as a named component with its own scoped styles from the start.
The need is purely for assistive tech, hiding a label or showing focus? Use .sr-only or .focus-ring. Infrastructure, not styling.

Sources

Utility-first model and the extract-to-component threshold: Tailwind CSS (tailwindcss.com) and Adam Wathan, CSS Utility Classes and Separation of Concerns (adamwathan.me). The composition-plus-blocks balance follows Andy Bell, CUBE CSS (cube.fyi). The visually-hidden recipe: W3C WAI WCAG technique C7 (w3.org) and Scott O'Hara, Inclusively Hidden (scottohara.me); it ships near-identically as Bootstrap .visually-hidden and Tailwind .sr-only. Visible focus is WCAG 2.1 SC 2.4.7 (w3.org). The exact class names, token bindings, and the reading of .sr-only and .focus-ring as required infrastructure are specific to this system.