Skip to main content

Search rules

Search all UI Guides rules by name, category, or source

layoutTailwind

Create Custom Utilities with @utility

SHOULD

SHOULD: Create custom utilities in @layer utilities for missing CSS properties (text-wrap, scrollbar)

Register project-specific utilities with the @utility directive, the only form that supports variants

Bad

Good

Why it matters

Tailwind does not ship every CSS property — `scrollbar-width`, `text-wrap: balance` on an older target, `mask-type` — so you will need to add your own. In v4 there is exactly one correct way, and it is `@utility name { … }`. This is not a stylistic preference over the old `@layer utilities { .name { … } }` form: that form no longer registers anything with the compiler, so `md:scrollbar-hide` and `hover:scrollbar-hide` simply do not exist and quietly do nothing at the call site.

`@utility` puts the name in Tailwind's registry, which buys three things a plain class cannot have: every variant works, the utility is sorted by property count alongside the built-ins so overriding it behaves predictably, and it is only emitted when actually used. Two details worth knowing: `@utility` requires a top-level, unnested rule (no `&` selectors, no nesting — that is what makes it variant-composable), and a trailing `-*` makes it take a value, so `@utility tab-*` plus `--tab-size-*` theme tokens gives you `tab-2`, `tab-4`, and `tab-[13]`.

Built by Gleb Stroganov, design engineer at Evil Martians.

The rules come from other people's skills and guidelines — Vercel, Rauno Freiberg, @Ibelick, impeccable, Emil Kowalski, Tailwind, RAMS — each one credited on the Sources page. The work here is extraction and wiring: every rule is pulled into one corpus, given a good and a bad example you can operate, a MUST/SHOULD/NEVER rule an agent can paste, and a link back to where it came from.