Utilities

The component layer

The precompiled @stisla/css bundle covers the component layer alone. It carries no grid system and no spacing, flex, or sizing utilities, by design. Every demo on this site arranges its components with Tailwind classes (flex, gap-4, grid, w-full), and those work here because the docs compile Tailwind. A page that only links stisla.css will not have them.

So if you copy a demo and the layout collapses, this is why. You have two ways to add the utility surface. Both run the Tailwind CLI as a build step. The difference is whether you keep the precompiled bundle or compile the components yourself.

Option A. Build from source

The clean default for a new project. Stop linking the precompiled stisla.css and compile your own stylesheet instead. Tailwind comes in once, so the reset, the token theme, and the utilities all land exactly once, with no duplication to reason about.

Author one input stylesheet. Pull in Tailwind, then the token theme, then the components. The components.css barrel imports every component in one line.

Important: Tailwind only generates the utility classes it actually finds in your markup. It auto-detects templates in most projects, so this usually needs nothing. But if your HTML or components live where it can’t reach, your flex and gap-4 come out missing and layouts collapse. Add the @source line above, pointing at those files. The Telling Tailwind what to scan section covers it in full.

Compile it, watching for changes during development.

The barrel is pure grouping. It re-imports the same raw component files you could list one by one, so the output is identical either way. When you want only the components you use (a smaller build, or any subset), swap the barrel for individual imports like @stisla/style/button.css. The Optimization page covers that subset path, and this is the same setup the Theming and Styling pages call the build path. The JavaScript runtime is separate and unchanged; see Installation.

Option B. Add utilities to the precompiled bundle

Keep the curated stisla.css exactly as it is and generate a second stylesheet that holds only the utilities. The bundle already carries the reset and the token theme, so you must not pull the whole of Tailwind in again next to it, which would emit a second reset and re-declare every token. Reference those parts instead of importing them.

The two @reference lines load Tailwind and the Stisla theme for context only. They teach the generator the spacing scale and the semantic colors (so gap-4 tracks --spacing and bg-primary resolves to the brand token) while emitting nothing themselves. Only the utilities layer is written out, so it drops onto the bundle without a second reset or re-declared tokens.

The same content rule from Option A applies here. Only the utilities Tailwind finds in your markup are generated, so add an @source line if it doesn’t auto-detect your templates (see Telling Tailwind what to scan).

Link the generated file after the bundle.

Now stisla.css stays untouched and your utilities.css adds only what is missing, with one reset in the page and no duplicated tokens.

Which one

• Option A for a new project, or any time you already compile CSS. One file holds everything, and it unlocks subsetting and compile-time token baking on the same build.
• Option B when stisla.css is already deployed and you only need to layer utilities on top. It is the smaller change and leaves the bundle exactly as shipped.

Most projects need one. Framework apps (React, Vue) almost always land on Option A, because they already run a build and import Tailwind once at the root; the utility surface comes for free there and this page is really for the no-build path.

Telling Tailwind what to scan

Either option only generates the utility classes it actually finds in your markup. Tailwind v4 auto-detects template files in your project, so most setups need no configuration. If your HTML or component templates live somewhere it does not reach, point at them explicitly in the input stylesheet.

Laying out components

With utilities available, you arrange components the ordinary Tailwind way. A handful of classes covers almost everything. Flex for a row or a stack, grid for a matrix, and the spacing scale for the gaps between.

A row

flex items-center gap-3 lines components up on one axis. flex-wrap lets them spill onto a second line on narrow screens, and ml-auto pushes one item to the far edge.

A stack

flex flex-col gap-3 stacks components vertically with even spacing. max-w-sm caps the width so a form does not stretch across the whole page.

A grid

grid grid-cols-2 gap-4 lays cards out in a matrix. For a layout that reflows by screen size, add responsive prefixes like sm:grid-cols-2 lg:grid-cols-3; the count steps up as the viewport widens.

A split layout

Mix grid with col-span-* for a main-and-aside split. The components keep reading from the same tokens, so the two regions stay coherent for free.

Tweaking the fit

Utilities also handle the small adjustments where a component sits a little wrong in its context. A full-width button in a narrow column, a touch of margin, a one-off corner. Because utilities compile into a later cascade layer than components, a utility wins over the component’s own rule with no specificity fight.

Reach for a utility when the change is about how a component fits the layout around it. When the change is about the component itself, a different radius for every button in the app, a recurring restyle, set its variable instead; the Styling page covers that side, and Composition covers when a recurring pattern should graduate into its own class.

One link worth keeping in mind: the spacing utilities (gap-*, p-*, m-*) are multiples of --spacing, the same base that drives component density. Dial --spacing for a region and the layout gaps reflow along with the components inside it. See Density for that token.