Utilities

Philosophy

A utility class changes one property on an existing shape. A button that needs a custom height. A card row that needs to be flex. A stack that needs more gap. A heading that needs muted color in one specific place. That’s what utilities are for.

What utilities are not for: assembling a new component from scratch. If you find yourself stacking .d-flex .gap-3 .p-4 .rounded .border on a <div> to build something that looks like a card, you’re using the wrong tool. Build the component in SCSS with its own BEM class, tokens, and color-mix states. The component file is small, scoped, deletable, and lets the next person reading your codebase see what the thing actually is.

Stisla is a design spec realized as components. Utilities are escape hatches. They aren’t Lego bricks. If composing utilities into components is your preferred workflow, reach for Tailwind instead.

The shipped set is small on purpose. Text (color, weight, size, line-height, alignment, transform, overflow). Layout (display, flex, gap, margin, padding, sizing, position, overflow). If a property isn’t in those two lists, the answer isn’t “add a new utility”. It’s “the component owns this”.

Text

Typography tweaks. Class names track the underlying property. Use .fw-* for weight, .fs-* for size, .lh-* for line height, and .text-* for color, alignment, transform, and overflow.

<div class="d-flex flex-column">
  <p class="fw-semibold fs-5 text-primary">Semibold, fs-5, primary color.</p>
  <p class="fw-light text-muted-foreground">Light weight, muted color.</p>
  <p class="text-truncate" style="max-width: 18rem;">A long sentence that will truncate with an ellipsis once it exceeds the container width.</p>
  <p class="text-uppercase text-center fs-1">Uppercased, centered, fs-1.</p>
</div>

Color

Weight

Size

Numeric scale, ascending small → large. Same direction as .gap-* and .m*-*. Use .fs-{breakpoint}-{step} for breakpoint-up variants.

Line height

Alignment, transform, overflow

Accessibility

Layout

Spacing uses a Tailwind-style 4 px linear scale (1=4 px, 2=8 px, 3=12 px, 4=16 px, 5=20 px, 6=24 px, 8=32 px). Every value multiplies by --st-density so the global density knob retunes spacing alongside component padding.

Margin and padding use CSS logical properties (margin-block-start, margin-inline-end, ...) so the same class works in LTR and RTL.

<div class="d-flex gap-3 align-items-center">
  <button type="button" class="btn btn--primary">Save</button>
  <button type="button" class="btn btn--neutral">Cancel</button>
  <span class="text-muted-foreground fs-2 ms-auto">Edited 2 min ago</span>
</div>

One flex row with a 12 px gap and an end-aligned timestamp pushed by .ms-auto. No new component, just three buttons and a span getting a layout tweak.

<div class="d-flex flex-column gap-2" style="max-width: 18rem;">
  <label for="email" class="form-label">Email</label>
  <input type="email" id="email" class="input" placeholder="you@example.com" />
  <p class="text-muted-foreground fs-2 mb-0">We'll never share your address.</p>
</div>

A vertical stack with an 8 px gap between rows. Note the helper text uses .mb-0 to kill its natural bottom margin so the gap owns the rhythm.

Display

Flex direction & wrap

Flex grow & shrink

Justify & align

Gap

.gap-{n} sets both row and column gap. .row-gap-{n} and .column-gap-{n} target one axis. Values: 0 / 1 / 2 / 3 / 4 / 5 / 6 / 8.

Margin & padding

Direction abbreviations follow Bootstrap convention: top, bottom, start, end, x for both inline sides, y for both block sides. Start and end use logical properties so RTL flips for free. Same step scale as gap.

Sizing

Percentage widths and heights resolve against the containing block. .h-* needs a sized parent to be meaningful.

Position

Overflow

Responsive

Insert a breakpoint name into any responsive-enabled class to make it apply from that width up. The mobile-first base lays the default. Each breakpoint cascades on top via min-width.

<div class="d-flex flex-column flex-md-row gap-3 align-items-md-center">
  <div class="w-100 w-md-50">
    <div class="card">
      <div class="card__body">Stacks on mobile.</div>
    </div>
  </div>
  <div class="w-100 w-md-50">
    <div class="card">
      <div class="card__body">Sits side&#8209;by&#8209;side from <code>md</code> up.</div>
    </div>
  </div>
</div>

Resize the preview frame. Below 768 px the row stacks (.flex-column) with each card at .w-100; at 768 px and above .flex-md-row + .w-md-50 kick in and the cards split the row.

Breakpoints

Same five breakpoints as the grid system.

What gets a responsive variant

These are the defaults. Every group is toggleable through $utilities-config, so this table shows what ships when the bundle is imported untouched.

Base-only by default: flex grow / shrink, align self, height, max-width / max-height, position, overflow, text color, font weight, line height, text transform, visually-hidden. Flip any of them on in $utilities-config.

Customizing the set

$utilities-config is the single override surface. Every group has an enabled flag and a responsive flag. Override the map before importing the bundle.

Toggling a group

Set responsive: true to add breakpoint variants to a group that ships base-only, or enabled: false to drop a group entirely.

// Override before the bundle import. map-merge preserves all other defaults.
$utilities-config: map-merge($utilities-config, (
  overflow:        (enabled: true,  responsive: true),
  position:        (enabled: true,  responsive: true),
  visually-hidden: (enabled: false, responsive: false),
));

@import '@stisla/css/bundles/stisla';

Emits .overflow-md-hidden, .position-lg-sticky, etc., and drops every .visually-hidden* class from the output. Disabled groups cost zero bytes.

Adding a new utility

You need two pieces. An entry in $utilities-config, and a matching @include utility-group(…) block. The helper handles base and breakpoint emission. $i is the empty string at base, and -sm / -md / … inside each breakpoint media query.

@import '@stisla/css/utilities/utilities';

$utilities-config: map-merge($utilities-config, (
  cursor: (enabled: true, responsive: false),
));

@include utility-group('cursor') using ($i) {
  .cursor#{$i}-pointer     { cursor: pointer     !important; }
  .cursor#{$i}-grab        { cursor: grab        !important; }
  .cursor#{$i}-not-allowed { cursor: not-allowed !important; }
}

Emits .cursor-pointer, .cursor-grab, .cursor-not-allowed. Flip responsive: true and the same block also emits .cursor-md-pointer etc. at every breakpoint.

All groups

Customization

Two knobs, no per-class vars.

Spacing values resolve through --st-density, the global lever from Customization that retunes every .gap-*, .m*-*, and .p*-* alongside component padding. Compact density (0.875) shrinks every utility step proportionally. Comfortable density (1.125) expands them.

Which groups ship, and which carry breakpoint variants, is set in $utilities-config. Disable groups you don’t use to drop them from the bundle. Flip responsive: true on a group to add breakpoint variants.