@sdxc/u
v2026.11.10
Published
Utility-first styling for remix/component, composed from small, terse mixins
Readme
@sdxc/u
Utility-first styling for remix/component, composed from small, terse mixins.
Every export is a mixin factory for a mix prop. Plain utilities set CSS properties, and wrapper
utilities (u.hover(), u.at(), u.dark(), ...) nest any other utilities under a selector or
at-rule. Token names resolve to --ui-* custom properties, and logical properties are the
default, each with a physical counterpart.
Installation
npm add @sdxc/uEvery utility returns a remix/component mixin, so remix
installs alongside this package.
Usage
Style an element
import * as u from "@sdxc/u";
<section mix={[u.p(4), u.rounded("lg"), u.surface("muted"), u.vstack({ gap: 3 })]}>
{children}
</section>;A number on a spacing utility multiplies the spacing scale (u.p(4) is
calc(var(--ui-spacing, 0.25rem) * 4)), and a string passes through as a raw CSS length
(u.p("1.5rem")). Box utilities follow the logical 1/2/4-value mapping: u.p(2, 4) is block
then inline.
Add state and responsive variants
import * as u from "@sdxc/u";
<button
mix={[
u.surface("brand"),
u.rounded("md"),
u.p(2, 4),
u.hover(u.bg("brand.tint")),
u.ring("brand"),
u.disabled([u.opacity(50), u.cursor("not-allowed")]),
u.at("md", u.p(3, 6)),
u.dark(u.border("neutral.strong")),
u.motionSafe(u.transition("background-color")),
]}
>
Save
</button>;A wrapper takes one utility, an array of them, or a falsy value, which it drops. u.at() is a
container query against the nearest ancestor declared with u.container(); u.media() is the
viewport query.
Import the theme
@import "@sdxc/u/theme.css";
:root {
--ui-color-neutral-50: oklch(0.985 0 0);
--ui-color-neutral-600: oklch(0.45 0 0);
/* ...every shade from 50 through 950 */
--ui-color-brand-50: oklch(0.97 0.02 250);
--ui-color-brand-600: oklch(0.52 0.18 250);
/* ...every shade from 50 through 950 */
}theme.css maps the neutral, brand, success, warning and danger tones
(--ui-{tone}-bg-tint, --ui-{tone}-fg, --ui-{tone}-border, ...) onto a palette the app
defines as --ui-color-{name}-{50..950}, and sets the spacing, container, font and text-size
scales. Add the dark class to an ancestor such as <html> for dark mode, or system to follow
prefers-color-scheme. Each class also sets color-scheme (dark, light dark), so
light-dark() colours and native controls under it match the tokens.
Color utilities take a tone with a suffix ("brand.tint", "brand.solid", "neutral.muted",
"brand.emphasis", "brand.onSolid", "neutral.strong"), a bare tone where the utility has a
default weight (u.fg("brand")), a palette shade ("color.neutral.950"), or any raw CSS color.
Import by family
import { bg, p } from "@sdxc/u";
import { hover } from "@sdxc/u/state";
import { ring } from "@sdxc/u/color/ring";
import { blur, spacing } from "@sdxc/u/tokens";
<a mix={[p(2), bg("neutral.tint"), hover(bg("brand.tint")), ring()]} />;
spacing(4); // "calc(var(--ui-spacing, 0.25rem) * 4)"
blur("sm"); // "var(--ui-blur-sm, 4px)"Each family (general, layout, size, color, typography, effects, overflow,
stacking, a11y, state, responsive, animation, transform) has its own entry point,
and each utility its own module under it (@sdxc/u/color/ring). @sdxc/u/tokens holds the string
resolvers; four of them (font, text, shadow, blur) share a name with a root utility.
Extend the token names
declare module "@sdxc/u" {
interface SemanticTones {
info: true;
}
interface ColorPalettes {
info: true;
}
}:root {
--ui-color-info-50: oklch(0.97 0.02 230);
--ui-color-info-600: oklch(0.52 0.18 230);
/* ... */
--ui-info-bg-tint: var(--ui-color-info-50);
--ui-info-bg-solid: var(--ui-color-info-600);
--ui-info-fg: var(--ui-color-info-600);
--ui-info-fg-on-solid: white;
--ui-info-border: var(--ui-color-info-200);
--ui-info-border-strong: var(--ui-color-info-600);
--ui-info-ring: var(--ui-color-info-500);
}Every token family (palettes, tones, radii, text sizes, fonts, containers, shadows, blurs) is an
interface an app extends through declaration merging. The utilities then accept the new name
(u.surface("info.tinted"), u.border("info")) and resolve it to the matching --ui-*
variable.
API
Every function returns a UtilityMixin for a mix prop unless its heading names another return
type. A parameter typed UtilityInput takes a UtilityMixin, a falsy value, or a nested array
of them. SpacingValue is a number on the spacing scale, "auto", or a raw CSS length;
SizeValue adds "full" for 100%. Filter, backdrop-filter, transform and box-shadow utilities
each write their own slot of one composite declaration, so u.blur() with u.grayscale(), or
u.shadow() with u.ringShadow(), combine instead of overriding each other.
General
calc(expression: string): string
Wraps a CSS calc() expression: calc({expression}). Returns a plain string, usable anywhere a utility accepts a raw CSS value, typically with u.var() to combine a custom property with an arithmetic operation.
counterIncrement(name: string, value?: number)
Applies counter-increment to the element's CSS counter, named by the bare counter identifier name. value is the integer the counter is incremented by; omit it to fall back to CSS's own default of 1.
counterReset(name: string, value?: number)
Applies counter-reset, creating or resetting the element's CSS counter named by the bare counter identifier name. value is the integer the counter is set to; omit it to fall back to CSS's own default of 0.
cursor(value: CursorValue | string)
Applies cursor. Accepts any CursorValue keyword — "pointer" for an interactive control, "not-allowed" for a disabled one, "default" to force the plain arrow — or an arbitrary string for a url(...) cursor.
combine(input: UtilityInput)
Flattens input and merges the flattened utilities' style trees into one declaration set at the host's own level, so unrelated utilities compose as a single mixin with each nested selector kept as a sibling.
env(name: string, fallback?: string): string
Resolves a CSS environment variable reference: env({name}), or env({name}, {fallback}) when a fallback is given. Returns a plain string, usable anywhere a utility accepts a raw CSS value.
if(condition: unknown, input: UtilityInput): UtilityMixin | false
Conditionally returns input as one mixin, or false when condition is falsy. A list (u.if(active, [u.bg("brand.solid"), u.fg("brand.onSolid")])) is merged through u.combine(), so it cascades as one unit.
mergeMix(base: MixInput, mix: MixInput): MixInput
Applies mix on top of base: the utilities of both render as one class with mix's in a later cascade sublayer, so they win on a property both set whatever selector base uses; other mixins apply unchanged. A component forwarding its caller's mix uses it: mix={u.mergeMix([u.text("sm"), u.fg("neutral")], mix)}.
listStyle(value: ListStyleValue = "none")
Applies list-style. Defaults to "none", the common case of a <ul> or <ol> serving as a plain layout container.
pointerEvents(value: PointerEventsValue = "none")
Applies pointer-events. Defaults to "none", the common case of an overlay, icon, or decorative element that should let clicks and hovers pass through to whatever's underneath it.
pseudoContent(value: string)
Applies the CSS content property, almost always on a ::before/::after pseudo-element. The pseudo prefix keeps the name distinct from @sdxc/u/layout's content(), which sets align-content.
raw(styles: CSSStyles)
Wraps a plain style object as a utility mixin, so bespoke declarations — a property outside this package's surface, or a call-site-computed value — compose inside wrappers like when(), whose inputs are utility mixins.
touchAction(value: TouchActionValue = "none")
Applies touch-action. Defaults to "none", the common case of a custom drag handle or gesture surface that handles its own touch input.
userSelect(value: UserSelectValue = "none")
Applies user-select. Defaults to "none", the common case of a label, icon, or drag handle that stays clear of highlight through an incidental click-drag.
var(name: string, fallback?: string): string
Resolves a custom property reference: var(--{name}), or with a fallback, var(--{name}, {fallback}). name omits the leading --, matching u.vars(); the raw string fits anywhere a utility takes a CSS value.
vars(values: Record<string, string | number>)
Sets custom properties on the host element, with the leading -- omitted from each key so call sites read as plain option names.
willChange(value: WillChangeValue)
Applies will-change, hinting the browser to optimize for an upcoming animation on the given property/properties before it starts.
Layout
absolute()
Sets position: absolute.
anchor(name: string, side: AnchorSide, fallback?: string): string
Resolves an anchor() reference to a plain string — the length an inset utility needs to pin an edge to the anchor's geometry. The leading -- is prepended; fallback keeps the inset valid when no anchor resolves.
anchorName(name: string)
Applies anchor-name, the declaring half of anchor positioning: it goes on the element anchored to, and positionAnchor points back at this name. The leading -- is prepended — an anchor name is a dashed-ident.
anchorSize(name: string, dimension: AnchorSizeDimension, fallback?: string): string
Resolves an anchor-size() reference to a plain string, letting a panel track its trigger's size in one browser-maintained declaration. The leading -- is prepended; fallback keeps it valid when no anchor resolves.
appearance(value: AppearanceValue | string = "none", options: AppearanceOptions = {})
Applies appearance (default "none", clearing a form control's native chrome) together with its -webkit- and -moz- twins; options.webkit / options.moz set to false drop a prefix.
basis(value: SizeValue = "auto")
Applies flex-basis, defaulting to "auto" to match the property's own initial value — the remainder of a flex: N N M shorthand once u.grow()/u.shrink() have been extracted from it.
block()
Sets display: block.
borderCollapse(value: BorderCollapseValue = "collapse")
Applies border-collapse. Defaults to "collapse", the common case of a table whose cell borders should merge into single lines instead of doubling up.
borderSpacing(value: string)
Applies the border-spacing property — the gap between adjacent table cell borders when border-collapse: separate is in effect (its default).
boxSizing(value: BoxSizingValue)
Applies box-sizing, controlling whether width/height (and the logical inline-size/block-size pair) span padding and border ("border-box") or the content area alone ("content-box", the CSS default).
center()
A zero-argument convenience pattern that centers content both ways. Composes u.flex(), u.items("center"), and u.justify("center"), so its output is exactly the declarations those three produce.
contain(value: ContainValue = "content")
Applies contain, letting the browser skip layout and paint work it can prove stays inside the subtree. Defaults to "content"; every value beyond "none" makes the element a containing block and a stacking context.
container(name: string, type: ContainerTypeValue = "inline-size")
Declares the host as a named container query context via the container shorthand (container-name and container-type together), so a descendant's u.at(size, name, ...) query can target it by name.
content(value: JustifyValue = "start")
Sets align-content, using the same accepted keywords and between/around/evenly aliasing as u.justify().
contentVisibility(value: ContentVisibilityValue = "auto")
Applies content-visibility so the browser skips rendering work for an element's contents; defaults to "auto". Long scrollable lists want virtualize, which also reserves a placeholder size for the scrollbar.
contents()
Sets display: contents, removing the host element's own box so its children participate directly in the parent's layout.
fieldSizing(value: FieldSizingValue = "content")
Applies field-sizing to an <input>, <textarea> or <select>. "content" (the default) sizes the control to its value; cap it with u.maxBs() or u.maxIs().
fixed()
Sets position: fixed.
flex()
Sets display: flex.
flexCol()
Sets flex-direction: column.
flexColReverse()
Sets display: flex; flex-direction: column-reverse.
flexRow()
Sets flex-direction: row.
flexRowReverse()
Sets display: flex; flex-direction: row-reverse.
flexWrap(value: "wrap" | "nowrap" | "wrap-reverse" = "wrap")
Sets flex-wrap, defaulting to wrap.
gap(...values: SpacingValue[])
Applies gap using the spacing scale or a raw CSS length. One value applies to both the row and column gap; two values are read as "{row} {column}".
grid()
Sets display: grid.
gridArea(name: string)
Applies grid-area, placing an element in a named area of its parent's grid-template-areas.
gridAutoColumns(value: SizeValue)
Applies grid-auto-columns to the implicit columns a grid creates past its explicit tracks. A number resolves on the spacing scale, "full" to 100%; raw strings such as minmax(...) reach CSS verbatim.
gridAutoFlow(value: GridAutoFlowValue = "row")
Applies grid-auto-flow, the axis auto-placed items fill along; defaults to "row". dense backfills earlier holes with later items, diverging visual order from the DOM order focus follows — keep it presentational.
gridAutoRows(value: SizeValue)
Applies grid-auto-rows to the implicit rows a grid creates past its explicit tracks. A number resolves on the spacing scale, "full" to 100%; raw strings such as minmax(...) reach CSS verbatim.
gridColumn(value: GridLineValue)
Applies grid-column, shorthand for grid-column-start / grid-column-end: one value sets the start line and spans one track, a "start / end" string sets both. A number always reads as a line number.
gridRow(value: GridLineValue)
Applies grid-row, placing or spanning a grid item along the block axis. A number is a line number: u.gridRow(2) starts the item at the second row line and occupies one track, while u.gridRow("span 2") occupies two.
gridTemplate(options: GridTemplateOptions = {})
Applies grid-template-columns/-rows/-areas from whichever option keys are given. Track lists vary too continuously for a named scale, so values are raw CSS strings; repeat builds the repeat(count, track) shape.
GridTemplateOptions: columns, rows and areas, each a raw CSS string.
grow(value: number | string = 1)
Applies flex-grow. Defaults to 1, the common case of a flexible item — a content area next to a fixed-size sidebar or icon — that should expand to fill whatever room is left in its flex container.
hidden()
Sets display: none, removing the host element from layout entirely.
hstack(options: StackOptions = {})
A horizontal flex stack. Composes u.flex(), u.flexRow(), and — from whichever option keys are given — u.gap(), u.items(), and u.justify().
StackOptions: gap (spacing scale), align (align-items) and justify (justify-content).
inline()
Sets display: inline.
inlineBlock()
Sets display: inline-block.
inlineFlex()
Sets display: inline-flex.
inlineGrid()
Sets display: inline-grid.
insBe(value: SpacingValue)
Applies inset-block-end — the trailing block edge, the bottom edge in a horizontal writing mode.
insBottom(value: SizeValue)
Applies the physical bottom property. Reach for it when the offset is genuinely tied to the physical bottom side; u.insBe() (inset-block-end) covers the logical block edge.
insBs(value: SpacingValue)
Applies inset-block-start — the leading block edge, the top edge in a horizontal writing mode.
insIe(value: SpacingValue)
Applies inset-inline-end — the trailing inline edge, which is the right edge in ltr and the left edge in rtl.
insIs(value: SpacingValue)
Applies inset-inline-start — the leading inline edge, which is the left edge in ltr and the right edge in rtl.
insLeft(value: SizeValue)
Applies the physical left property, for offsets genuinely tied to the viewport's left side. u.insIs() (inset-inline-start) covers the writing-direction-aware default.
insRight(value: SizeValue)
Applies the physical right property, for offsets genuinely tied to the viewport's right side. u.insIe() (inset-inline-end) covers the writing-direction-aware default.
insTop(value: SizeValue)
Applies the physical top property, for offsets genuinely tied to the viewport's top side. u.insBs() (inset-block-start) covers the writing-direction-aware default.
inset(...values: SpacingValue[])
Applies a logical inset shorthand from the spacing scale or a raw CSS length. One value covers every side; two map to block then inline; four map to block-start, inline-end, block-end, inline-start.
interpolateSize(value: InterpolateSizeValue = "allow-keywords")
Opts the element into animating to and from keyword sizes (auto, min-content, max-content, fit-content), so a transition to height: auto or block-size: auto animates across its full duration.
items(value: AlignItemsValue = "stretch")
Sets align-items ("start", "center", "end", "baseline", "stretch").
justify(value: JustifyValue = "start")
Sets justify-content, aliasing the short between/around/evenly forms to their space-* CSS keywords.
place(options: PlaceOptions = {})
Sets item and/or content placement on both axes from whichever option keys are given, so a partial options object emits only the declarations belonging to the keys it carries.
PlaceOptions: items (place-items) and content (place-content).
positionAnchor(name: string)
Points an absolutely or fixed positioned element (a tooltip, popover, or menu) at the anchor name anchorName declared on its target. Pass name bare; the -- custom-property prefix is added here.
positionArea(value: string)
Applies the CSS Anchor Positioning position-area property, placing an anchor-positioned element in a named region of the 3x3 grid around its anchor. Accepts the whole logical-position-keyword grammar as a string.
positionTryFallbacks(...values: string[])
Applies the CSS Anchor Positioning position-try-fallbacks property, listing named tactics or --custom-position-try references tried in order when the preferred position overflows its containing block.
relative()
Sets position: relative.
repeat(count: RepeatCount, track: RepeatTrack): string
Builds a repeat(...) track-list value string for u.gridTemplate()'s columns/rows options, or any grid-template-columns/-rows use, since track sizing varies too continuously for a named scale to usefully cover.
resize(value: ResizeValue = "block")
Applies resize, controlling which axes a user can drag the element's resize handle along. Defaults to "block", the shape most textareas want, and only takes effect on an element whose overflow is not visible.
self(value: AlignSelfValue = "auto")
Sets align-self.
shrink(value: number | string = 0)
Applies flex-shrink. Defaults to 0, the common case of a fixed-size flex item — an icon or graphic slot — that keeps its size alongside the flexible content next to it.
spacer()
A flexible spacer: grows and shrinks to fill whatever room is left in a flex container, pushing siblings on either side of it apart — a toolbar's trailing action pinned to the end, or two row groups split to the edges.
sticky()
Sets position: sticky.
virtualize(intrinsicSize: string)
Applies content-visibility: auto with contain-intrinsic-size so the browser skips rendering off-screen rows in a long list or table, using intrinsicSize as a placeholder so the scrollbar doesn't jump on mount.
vstack(options: StackOptions = {})
A vertical flex stack. Composes u.flex(), u.flexCol(), and — from whichever option keys are given — u.gap(), u.items(), and u.justify().
zstack(options: ZStackOptions = {})
A grid-overlay stack for layering children on top of each other. Composes u.grid() and, when given, u.items() for align-items; justify-items has no dedicated utility, so it's set directly.
ZStackOptions: align (align-items) and justify (justify-items).
Size
aspect(ratio: AspectRatioName) / aspect(width: number, height: number)
Applies aspect-ratio, either from a width/height pair or one of the named ratios in AspectRatioName. Ratios vary too continuously for a full token family to pay for itself, so only a handful of common shapes get names.
bleed(value: SpacingValue = 4)
Pulls the host past its container's inline padding by value on both sides via a negative inline margin — for a full-bleed image or divider inside an otherwise padded section, composing u.mi() with a negated length.
bs(value: SizeValue)
Applies block-size — the logical height, which is the physical width in a vertical writing mode.
circle()
A shape pattern for circular boxes: a square aspect ratio plus full radius — an avatar frame, a status dot, an icon badge. Composes u.aspect("square") and u.rounded("full").
corner(shape: CornerShape)
Applies corner-shape behind @supports, so browsers without it keep the plain border-radius shape.
fit(value: FitValue = "cover")
Applies object-fit, shaping how a container-sized media element (img, video) fills its box.
height(value: SizeValue)
Applies the physical height property, keeping element size tied to the viewport axis across writing-modes and directions. Prefer u.bs() (block-size) for content that should track the logical block axis.
is(value: SizeValue)
Applies inline-size — the logical width, which is the physical height in a vertical writing mode.
m(...values: SpacingValue[])
Applies logical margin using the spacing scale, "auto", or a raw CSS length. Follows the same 1/2/4-value logical mapping as p() — see MDN: logical properties.
marginLeft(value: SpacingValue)
Sets the physical margin-left property directly, pinned to the fixed left edge regardless of writing direction. Prefer u.mi() (margin-inline) for direction-aware margins.
marginRight(value: SpacingValue)
Sets the physical margin-right property directly, pinned to the fixed right edge regardless of writing direction. Prefer u.mi() (margin-inline) for direction-aware margins.
paddingLeft(value: SpacingValue)
Applies the physical padding-left property, for padding pinned to a fixed, physical viewport edge — such as a safe-area-inset offset on a docked panel. Prefer u.pis()/u.pi() for logical inline padding.
paddingRight(value: SpacingValue)
Applies the physical padding-right property, for padding pinned to a fixed, physical viewport edge — such as a safe-area-inset offset on a docked panel. Prefer u.pie()/u.pi() for logical inline padding.
maxBs(value: SizeValue)
Applies max-block-size.
maxHeight(value: SizeValue)
Applies the physical max-height property, for components whose sizing tracks the physical viewport axis. Use u.maxBs() (max-block-size) for the logical block-axis default.
maxIs(value: SizeValue)
Applies max-inline-size.
maxWidth(value: SizeValue)
Applies the physical max-width property, for elements whose sizing is genuinely tied to the physical viewport axis. Prefer u.maxIs() (max-inline-size) for the logical default.
mb(...values: SpacingValue[])
Applies margin-block. One value applies both block edges; two values map to block-start then block-end.
mbe(value: SpacingValue)
Applies margin-block-end — the trailing block edge, the bottom edge in a horizontal writing mode.
mbs(value: SpacingValue)
Applies margin-block-start — the leading block edge, the top edge in a horizontal writing mode.
mi(...values: SpacingValue[])
Applies margin-inline. One value applies both inline edges; two values map to inline-start then inline-end.
mie(value: SpacingValue)
Applies margin-inline-end — the trailing inline edge, which is the right edge in ltr and the left edge in rtl.
minBs(value: SizeValue)
Applies min-block-size.
minHeight(value: SizeValue)
Applies the physical min-height property. Prefer u.minBs() (min-block-size) unless the element's sizing must track the physical viewport axis regardless of writing-mode or direction.
minIs(value: SizeValue)
Applies min-inline-size.
minWidth(value: SizeValue)
Applies the physical min-width property, for elements whose sizing is tied to the physical viewport axis. Prefer u.minIs() (min-inline-size) for the logical default.
mis(value: SpacingValue)
Applies margin-inline-start — the leading inline edge, which is the left edge in ltr and the right edge in rtl.
objectPosition(value: ObjectPositionValue = "center")
Applies object-position, choosing which part of a replaced element's cropped content stays visible, keeping a subject's face in frame once u.fit("cover") crops it. Only works with u.fit() on replaced elements.
p(...values: SpacingValue[])
Applies logical padding using the spacing scale or a raw CSS length. One value applies all sides; two values map to block then inline; four values map to block-start, inline-end, block-end, and inline-start.
pb(...values: SpacingValue[])
Applies padding-block. One value applies both block edges; two values map to block-start then block-end.
pbe(value: SpacingValue)
Applies padding-block-end — the trailing block edge, the bottom edge in a horizontal writing mode.
pbs(value: SpacingValue)
Applies padding-block-start — the leading block edge, the top edge in a horizontal writing mode.
pi(...values: SpacingValue[])
Applies padding-inline. One value applies both inline edges; two values map to inline-start then inline-end.
pie(value: SpacingValue)
Applies padding-inline-end — the trailing inline edge, which is the right edge in ltr and the left edge in rtl.
pis(value: SpacingValue)
Applies padding-inline-start — the leading inline edge, which is the left edge in ltr and the right edge in rtl.
safeAreaPadding(side: SafeAreaSide, fallback: string = "0px")
Pads the given physical side by its env(safe-area-inset-{side}) value, falling back to fallback ("0px" by default) on platforms with no safe area to avoid. Sets only that one physical padding property.
squircle(name: RadiusName | string = "md")
A shape pattern for continuous rounded corners: sets a radius, then refines it with corner-shape where supported, so every browser renders at least the plain rounded shape. Composes u.rounded() and u.corner().
width(value: SizeValue)
Applies the physical width property, for an element whose sizing is tied to the physical viewport axis; u.is() (inline-size) covers sizing along the logical inline axis.
Color
accent(value: ColorValue | string = "brand")
Applies accent-color, the property native form controls (checkbox, radio, range, progress) read for their own painted color. Defaults to the brand solid color so a bare u.accent() always resolves.
autofill(background?: ColorValue | string, foreground?: ColorValue | string)
Overrides the browser's autofill background and text color under &:-webkit-autofill, so an autofilled input keeps the appearance every other input has. Defaults to the system background/foreground tokens.
bg(value?: ColorValue | string) / bg(options: BgOptions)
Applies background-color, or the full set of background properties when given an options object, of which only the given keys are set. A semantic tone requires a tint/solid suffix so the call site states its weight.
BgOptions: color, image, size, position, repeat, attachment, clip ("text" clips the background to the glyphs).
border(value?: ColorValue | string) / border(options: BorderOptions)
Applies border-color, or the full set of border properties when given an options object, of which only the given keys are set. A bare tone resolves its plain border weight, which the theme promotes under high contrast.
BorderOptions: color, width (a number is pixels), style ("solid" when only width is given), and noStyleDefault to leave the style to another rule. u.border("none") removes the border.
borderEdge(edge: BorderEdge, options: BorderEdgeOptions = {})
Applies a border to a single edge only, for a divider between two adjacent elements (e.g. two stepper buttons sharing one frame). Only the given keys are set; prefer a logical edge so the divider follows writing mode.
edge is "block-start", "block-end", "inline-start", "inline-end" or a physical side; BorderEdgeOptions takes the same keys as BorderOptions.
caretColor(value?: ColorValue | string)
Sets caret-color for an editable field, resolving a tone at its fg weight. With no value it emits "auto", deriving the caret from the field's text color; pass a tone when that reads near-invisible on a tint.
colorMix(colorSpace: string, ...stops: ColorMixStop[]): string
Builds a color-mix(...) value string for any color-accepting property. colorSpace is the raw interpolation space CSS expects ("oklab", "srgb", "hsl", ...).
colorScheme(value: ColorSchemeValue = "light dark")
Sets color-scheme, which tells the browser which schemes an element renders correctly in, so the chrome the browser paints itself — scrollbars, pickers, form controls — follows the theme. It inherits: set it on <html>.
fg(value?: ColorValue | string)
Applies color (foreground text color). Called with no value it resolves the tiny system default (var(--ui-fg, CanvasText)); called with a bare tone it defaults to that tone's plain fg weight.
fill(value?: ColorValue | string)
Applies the SVG fill paint property, resolving semantic tones the same way color does. With no value it resolves the system default (var(--ui-fg, CanvasText)); a bare tone resolves that tone's fg weight.
fillOpacity(value: number | string)
Sets the SVG fill-opacity paint property. A bare number is read as a 0-100 integer, matching u.opacity().
conicGradient(angle: number | string, ...stops: GradientStop[]): string
Builds a conic-gradient(...) value string for any background-image use. A numeric angle is treated as degrees and wrapped in the from keyword CSS requires; a string passes through as the full from ... at ... clause.
linearGradient(angle: number | GradientDirection, ...stops: GradientStop[]): string
Builds a linear-gradient(...) value string for any background-image use. A numeric angle is treated as degrees; a string passes through unchanged, so CSS's own side/corner keywords work too.
radialGradient(shape: GradientShape, ...stops: GradientStop[]): string
Builds a radial-gradient(...) value string for any background-image use. shape is the raw shape/size/position clause CSS expects, so a compound clause such as "ellipse at top left" passes through unchanged.
outline() / outline(color: ColorValue | string) / outline(width: number) / outline(color: ColorValue | string, width: number) / outline(options: OutlineOptions)
Applies an outline unconditionally, for a persistent or decorative edge. A bare string is a color, a bare number is a width in pixels, the two together set both, and an options object sets every property at once.
OutlineOptions: color (the system ring color by default), width (2 by default, pixels), style ("solid"), and offset.
outlineColor(value?: ColorValue | string)
Sets outline-color alone, so a state such as [aria-invalid] can tint an outline while the width and style already in effect stay in force. With no argument it resolves the system default ring color.
outlineStyle(value: OutlineStyleValue)
Sets outline-style alone, so a state can override the style while the color and width already in effect stay in force.
outlineWidth(value: number | string)
Sets outline-width alone, so a state can override the width while the color and style already in effect stay in force. A bare number is treated as pixels; a string passes through unchanged.
ring(value?: ColorValue | string)
Applies a focus ring already scoped to &:focus-visible, so it shows for keyboard and assistive-tech focus and a component can apply it directly.
stroke(value?: ColorValue | string)
Applies stroke, resolving a semantic tone to an SVG shape's outline color. With no value it resolves the system default var(--ui-fg, CanvasText); a bare tone resolves that tone's fg weight.
strokeLinecap(value: "butt" | "round" | "square")
Sets stroke-linecap, the SVG paint property controlling how a <path>/<line> shape's stroke renders at the two open ends of an unclosed subpath.
strokeLinejoin(value: "miter" | "round" | "bevel")
Sets stroke-linejoin, the SVG paint property controlling how a <path>/<polyline>/<polygon> shape's stroke renders at a corner between two segments.
strokeWidth(value: number | string)
Sets stroke-width on an SVG shape. A bare number stays a unitless SVG user-unit value, so the stroke scales with the SVG's own coordinate system; a string passes through for a value that needs an explicit unit.
surface(recipe: SurfaceRecipe = "default")
Composes u.bg(), u.fg(), and u.border() so a surface's contrast holds by construction. Accepts recipe names only, because a surface's background, foreground, and border must be chosen as one matching set.
translucent(name: BlurName | string = "md")
A see-through background plus backdrop blur, gated behind prefers-reduced-transparency: no-preference; a reduced-transparency preference gets the opaque --ui-bg background and stays legible.
vectorEffect(value: "none" | "non-scaling-stroke" | "non-scaling-size" | "non-rotation" | "fixed-position")
Sets vector-effect, exempting an SVG shape from its ancestor transforms: "non-scaling-stroke" keeps a chart line's stroke width constant while the chart itself scales or zooms.
Typography
balance()
Balances line lengths across a wrapped block, best suited to short text such as headings, since browsers cap balancing to a small number of lines. Use pretty for long-form body copy.
font(name: FontFamilyName | string)
Applies font-family from the named font scale (sans, serif, mono, or an app-extended name) via var(--ui-font-{name}, fallback). "inherit" and "unset" pass through unchanged as literal CSS keywords.
fontSize(name: TextSizeName | string)
Applies font-size from the named text scale (xs through 9xl, or an app-extended name), resolving the same token as u.text()'s font-size half but touching only font-size, leaving line-height fully caller-set.
fontVariantNumeric(value: FontVariantNumericValue = "tabular-nums")
Sets font-variant-numeric; u.tabularNums() covers the common tabular-nums case and shares the same declaration. Each keyword names an OpenType feature — a font that lacks it renders unchanged digits.
hyphens(value: HyphensValue = "auto")
Lets long words break with a hyphen instead of forcing the line short. "auto" hyphenates only when the element or an ancestor carries a lang attribute to pick a dictionary from — omit it and nothing hyphenates.
leading(value: LeadingValue = "normal")
Applies line-height. Named values resolve through var(--ui-leading-{name}, fallback), so an app can override the scale without losing the default; numbers and other strings pass through unchanged.
lineClamp(lines: number)
Clamps text to lines lines, ending in an ellipsis, through -webkit-line-clamp.
nowrap()
Prevents text from wrapping onto multiple lines, letting it overflow its box instead. Pair with truncate when overflow should end in an ellipsis rather than spill out.
overflowWrap(value: OverflowWrapValue = "break-word")
Applies overflow-wrap, breaking a word only when it would otherwise overflow a bounded inline size, while ordinary text keeps its normal break points — ideal for a long URL, hash, or identifier in a narrow column.
pretty()
Avoids leaving a short orphan word alone on the last line of a wrapped block, scaling to long-form body copy since browsers don't cap how many lines it applies to.
tabSize(value: number | string = 2)
Applies tab-size. A bare number is stringified so it stays unitless — CSS would otherwise read it as a px length — while a string such as "4ch" passes through unchanged as a CSS length.
tabularNums()
Applies font-variant-numeric: tabular-nums, so digits render at a fixed width instead of their proportional metrics — a running total, countdown, or one-time-code field reads without its layout shifting as digits change.
text(name: TextSizeName | string)
Applies font-size and its paired line-height from the named text scale through matching var(--ui-text-*) / var(--ui-leading-*) properties, so an extended name inherits a sensible default leading before defining one.
textAlign(value: TextAlignValue = "start")
Applies text-align using the logical start/end keywords so alignment flips automatically under dir="rtl". A raw value such as "left" or "right" is also accepted for alignment that must stay physical.
textDecoration(value?: TextDecorationLineValue) / textDecoration(options: TextDecorationOptions)
Applies text-decoration-line from a bare value, or sets only the given keys from a text-decoration options object. thickness and offset are kept separate because text-decoration's shorthand cannot set or reset them.
TextDecorationOptions: line, color, style, thickness and offset (numbers are pixels).
textTransform(value: TextTransformValue)
Applies text-transform.
tracking(value: TrackingValue = "normal")
Applies letter-spacing from the named tracking scale, resolving through var(--ui-tracking-{name}, fallback) so the scale works before an app defines the variable; any other string is treated as a raw letter-spacing value.
truncate()
Truncates single-line text with an ellipsis once it overflows its box; requires a bounded inline size (max-inline-size, a flex/grid item with min-inline-size: 0, or similar) or there is nothing to overflow against.
type(name: TextSizeName | string)
Applies u.text(name) plus the sans font family; pair u.text() with u.font() for another family.
verticalAlign(value: VerticalAlignValue)
Applies vertical-align, e.g. for aligning an inline-block icon against adjacent text.
weight(value: FontWeightValue = "normal")
Applies font-weight. Named values alias the standard numeric weight scale (thin 100 through black 900); a raw number passes through unchanged for values the named scale doesn't cover.
whiteSpace(value: WhiteSpaceValue = "pre-wrap")
Applies white-space; also written by u.nowrap(), u.truncate(), and u.visuallyHidden(), so pick one. Defaults to pre-wrap, keeping preformatted line breaks while still wrapping in a narrow container.
wordBreak(value: WordBreakValue = "normal")
Applies word-break.
Effects
backdropBlur(name: BlurName | string = "md")
Blurs the backdrop by a step from the blur scale, whatever the user's transparency preference; u.translucent() is the gated variant with a solid fallback. Sibling utilities combine through the shared composite filter.
backdropBrightness(value: number | string = 1.1)
Scales the backdrop's lightness — below 1 darkens, above 1 brightens — keeping overlaid text legible. Needs a partly transparent host background; combines with sibling backdrop utilities; u.transparencySafe() gates it.
backdropContrast(value: number | string = 1.25)
Pushes the backdrop away from (above 1) or toward (below 1) mid-grey; flattening it to a uniform tone keeps overlaid text legible. Needs a partly transparent host; sibling utilities combine; u.transparencySafe() gates it.
backdropDropShadow(options: BackdropDropShadowOptions = {})
Shadows the shapes showing through the host. The shadow shows only where the backdrop is transparent, so the shapes need their own backdrop root (a parent with willChange("filter")); over an opaque page it paints nothing. u.transparencySafe() gates it.
BackdropDropShadowOptions takes the same x, y, blur and color keys as DropShadowOptions.
backdropGrayscale(value: number | string = 1)
Desaturates the backdrop toward grey (1 fully, 0 untouched) so a coloured overlay reads as the only hue in the area. Needs a partly transparent host; combines with sibling utilities; u.transparencySafe() gates it.
backdropHueRotate(value: AngleValue = 90)
Rotates the backdrop's hue while preserving lightness and saturation, so a busy backdrop pulls toward one brand hue with its light/dark structure intact. Needs a partly transparent host; u.transparencySafe() gates it.
backdropInvert(value: number | string = 1)
Inverts the colours showing through the element's translucent background. Composes with every other backdrop utility through the shared composite backdropFilter; wrap in u.transparencySafe() for a solid fallback.
backdropOpacity(value: number | string = 0.5)
Fades what shows through the element's translucent background, taking CSS's native 0–1 range or a percentage string. Composes with every other backdrop utility; wrap in u.transparencySafe() for a solid fallback.
backdropSaturate(value: number | string = 1.4)
Boosts or mutes the saturation of what shows through the element's translucent background. Composes with every other backdrop utility; wrap in u.transparencySafe() for a solid fallback.
backdropSepia(value: number | string = 1)
Shifts what shows through the element's translucent background toward a warm brown monochrome. Composes with every other backdrop utility; wrap in u.transparencySafe() for a solid fallback.
backfaceVisibility(value: BackfaceVisibilityValue = "hidden")
Controls whether the back face of a 3D-transformed element renders once it rotates away from the viewer; the "hidden" default keeps flip-card and page-turn effects showing only their front face.
blur(name: BlurName | string = "md")
Applies a blur from the blur scale by writing only its own --ui-filter-blur custom property, so it combines with u.grayscale(), u.brightness(), and every other filter utility in one composite filter.
brightness(value: number | string = 1.1)
Applies a filter: brightness(...), scaling every pixel's lightness. Values below 1 darken and above 1 brighten; 0 is solid black.
contrast(value: number | string = 1.25)
Applies a filter: contrast(...), pushing pixels away from (above 1) or toward (below 1) mid-grey; 0 flattens the element to uniform grey. Composes with every other filter utility through the shared composite filter.
dropShadow(options: DropShadowOptions = {})
Applies filter: drop-shadow(...), shadowing the element's rendered shape — a PNG's alpha channel, an SVG icon's outline — with offsets and a blur radius. Composes with every filter utility through the shared composite filter.
DropShadowOptions: x (default 0), y (1) and blur (2) on the spacing scale or as raw lengths, and color.
filterOpacity(value: number | string = 0.5)
Applies a filter: opacity(...), fading the element inside the filter pipeline so one pass carries the fade along with any blur() or grayscale(). Takes CSS's native 0–1 range, or a percentage string.
grayscale(value: number | string = 1)
Applies a filter: grayscale(...), desaturating toward grey; 1 (the default) is fully grey, dimming an inactive element while its layout holds. Purely visual, so pair it with a cue assistive technology can read.
hueRotate(value: AngleValue = 90)
Applies a filter: hue-rotate(...), rotating every pixel's hue by the given angle while preserving lightness and saturation, so one source asset can be retinted per theme. A bare number is degrees; strings pass through as-is.
invert(value: number | string = 1)
Inverts colors (1, the default, fully) to flip single-color raster assets for dark mode. Composes through the shared composite filter declaration, so it combines with every other filter utility.
mask(image: string) / mask(options: MaskOptions)
Applies a CSS mask image, or the given subset of mask properties when passed an options object. Every property is mirrored onto its -webkit- prefixed twin, which Safari requires to render an element mask.
MaskOptions: image, size, position, repeat and mode.
mixBlendMode(value: MixBlendModeValue = "multiply")
Blends the element with the content painted behind it. Any value but normal makes the element its own stacking context, and blending stops at the nearest one — put u.isolate() on the ancestor that should bound it.
opacity(value: number)
Applies opacity from a 0-100 integer. Sets the opacity property, which flattens the element and all of its descendants into one group and fades that group as a whole.
ringShadow(value: ColorValue | string, width: number | string = 2)
Draws a selection ring that stays visible for as long as a component applies it, for persistently-selected swatches, chips, and thumbnails. Occupies the composite boxShadow ring slot, painting inside u.shadow()'s elevation.
rounded(name: RadiusName | string = "md")
Applies border-radius from the radius scale (none, sm, md, lg, xl, full) or a raw CSS length.
roundedCorner(corner: LogicalCorner, name: RadiusName | string = "md")
Applies a radius from the radius scale, or a raw CSS length, to one logical corner — for shapes that round three corners uniformly and differentiate the fourth, like a chat bubble's tail.
saturate(value: number | string = 1.5)
Applies a filter: saturate(...) to the element itself, where 0 is fully desaturated and values above 1 oversaturate. Writes into the shared composite filter declaration, so it stacks with every other filter utility.
sepia(value: number | string = 1)
Applies a filter: sepia(...), shifting the element toward a warm brown monochrome; 1 (the default) is a full conversion. Writes into the shared composite filter declaration, so it stacks with every other filter utility.
shadow(name: ShadowName | string = "md")
Applies a box shadow from the shadow scale, written to the elevation slot of the shared composite boxShadow declaration. Claiming only that slot lets an elevation shadow and a u.ringShadow() render as two stacked layers. "none" clears the slot and a raw CSS shadow passes through.
textShadow(options: TextShadowOptions = {})
Applies text-shadow, tracing the glyph forms themselves. The practical use is keeping text legible over an image or video; a translucent scrim between the media and the text stays the reliable fix, with this layered on top.
TextShadowOptions: x (default 0), y (1) and blur (2) on the spacing scale or as raw lengths, and color (a translucent black by default).
transition(properties: string, options: TransitionOptions = {})
Applies the transition-property/transition-timing-function/ transition-duration triplet behind most hover, focus, press and selection state changes, so a call site only names which properties animate.
TransitionOptions: duration (a number is milliseconds, 150 by default) and easing (cubic-bezier(0.4, 0, 0.2, 1) by default).
transitionBehavior(value: TransitionBehaviorValue)
Applies the transition-behavior property on its own; "allow-discrete" lets a discrete property such as display or content-visibility animate across a transition, commonly paired with @starting-style.
transitionDelay(value: string = "0s")
Applies transition-delay on its own, so items sharing one transition can stagger by giving each an increasing delay. Keep the stagger on the entering state and leave the leaving state at 0s, so dismissal stays immediate.
transitionDuration(value: string)
Applies transition-duration on its own, so a media query such as prefers-reduced-motion can shrink an already-declared transition to zero while its property list and timing function stay in place.
transitionProperty(value: string)
Applies transition-property on its own, so a variant can change which properties animate while the duration and timing function declared elsewhere stay in place.
visibility(value: VisibilityValue = "visible")
Controls the CSS visibility property: a "hidden" element keeps its layout box and can transition back to "visible", which is what a selection indicator or hover-triggered surface needs to fade in place.
Overflow
clip()
Applies overflow: clip, the modern alternative to overflow: hidden. Overflow stays permanently unreachable: user input, programmatic scrolling, and focusing a clipped descendant all leave the element unscrolled.
divide(axis: DivideAxis = "block", colorOrWidth?: ColorValue | string | number, maybeWidth?: number)
Applies a divider border between every child except the last, along axis. A number in the color position is read as the border width, so a width can be set alone; a color name resolves through the semantic and palette tokens.
noScrollbar()
Hides the scrollbar across Chrome/Safari, legacy Edge, and Firefox, while the element stays scrollable by wheel, touch, keyboard, and script. Pair with u.scroll()/u.overflow() on the same element.
overflow(value: OverflowValue | { x?, y?, inline?, block? } = "hidden")
Applies overflow, defaulting to "hidden". An axis object sets only the axes it names and leaves the rest untouched; prefer its inline/block keys over x/y to stay correct under RTL and vertical writing modes.
overflowAnchor(value: OverflowAnchorValue = "none")
Applies overflow-anchor, the browser's choice of which element holds the scroll position steady as content above it resizes. The "none" default suits infinite-scroll sentinels, whose own growth fights anchoring.
overflowBlock(value: OverflowValue = "hidden")
Applies overflow-block, independently of the inline axis. The block axis follows writing mode and direction, so the utility stays correct under RTL and vertical writing modes.
overflowInline(value: OverflowValue = "hidden")
Applies overflow-inline, independently of the block axis. The inline axis follows writing mode and direction, so the utility stays correct under RTL and vertical writing modes.
overflowX(value: OverflowValue = "hidden")
Applies overflow-x, independently of the block axis.
overflowY(value: OverflowValue = "hidden")
Applies overflow-y, independently of the inline axis.
overscrollBehavior(value: OverscrollBehaviorValue = "contain")
Applies overscroll-behavior, defaulting to "contain": a scroll past the end stays inside this element and the platform affordance — iOS rubber-banding, Android pull-to-refresh — survives. "none" suppresses it.
scroll(axis: ScrollAxis = "both")
Turns the element into a scroll container that reveals a scrollbar only where content actually overflows the given axis, defaulting to "both". Composes u.overflowX("auto")/u.overflowY("auto") for the selected axis.
scrollBehavior(value: ScrollBehaviorValue = "smooth")
Applies scroll-behavior, defaulting to "smooth", so anchor jumps and programmatic scrolls animate. Smooth scrolling is motion: wrap the call in u.motionSafe() to honor a reduced-motion preference with an instant jump.
scrollMargin(...values: SpacingValue[])
Applies logical scroll-margin on a scroll item, growing the box the container aligns when it snaps to this item or an anchor jump targets it, so a sticky header clears only the items that need the extra room.
scrollPadding(...values: SpacingValue[])
Applies logical scroll-padding so a scroll snap position or anchor jump lands clear of a sticky header — set it to the header's height. Follows p()'s 1/2/4-value logical mapping; see MDN.
scrollSnapAlign(value: ScrollSnapAlignValue = "start")
Applies scroll-snap-align, defaulting to "start", on the snap items — the children of the scroll container — while u.scrollSnapType() goes on the container; swapping the two silently disables snapping either way.
scrollSnapStop(value: ScrollSnapStopValue = "always")
Applies scroll-snap-stop to a snap item, defaulting to "always" so a fast flick rests on the item and one swipe advances exactly one page. "normal" lets momentum carry past it.
scrollSnapType(axis: ScrollSnapAxis | "none" = "inline", strictness: ScrollSnapStrictness = "mandatory")
Applies scroll-snap-type to a scroll container, defaulting to "inline mandatory", the paged-carousel case; pass "none" to disable snapping. Snapped children need u.scrollSnapAlign().
scrollbarColor(thumb?: ColorValue | string, track?: ColorValue | string)
Themes a scroll container's scrollbar via the standard scrollbar-color property, supported by Firefox and modern Chromium alike through plain CSS. Inherits down the tree, theming nested scroll containers too.
scrollbarGutter(value: ScrollbarGutterValue = "stable")
Applies scrollbar-gutter, defaulting to "stable", so the container is already the size it settles at and content holds its position the moment a scrollbar appears. Takes effect on a scroll container (u.scroll()).
thinScrollbar()
Requests a thin scrollbar that reserves its gutter up front, so layout stays put whether or not the scrollbar is showing. Pair with u.scroll()/u.overflow() on the same scroll container.
Stacking
isolate()
Creates a new stacking context on the host element while preserving its layout, so a later z-index on this element (or a descendant) stays confined here, isolated from unrelated siblings outside it.
layer(value: number)
Composes isolate and z so a single call gets both a new stacking context and a stacking order. Accepts only numeric values, leaving named layers like "toast" or "modal" to app or component code.
z(value: number)
Sets the host element's z-index from a plain number. Named component layers such as "toast" or "modal" are an app or component concern, so this primitive stays scoped to raw numeric values.
Accessibility
debug(mode: boolean | "nested" = true)
Outlines the host in red while import.meta.env.DEV is true and emits nothing otherwise. false turns it off from a flag; "nested" extends the outline to every descendant to inspect a full box model.
forcedColorAdjust(value: ForcedColorAdjustValue = "none")
Applies forced-color-adjust, defaulting to "none" so author colours survive where colour itself carries the information — swatches, chart legends, syntax highlighting. Scope it with u.forcedColors().
visuallyHidden()
Clips the host to a 1px box taken out of layout flow, keeping its native focusability and tab order intact so screen readers and keyboard users still reach it.
State
active(input: UtilityInput)
Sugar over when("&:active", input).
after(input: UtilityInput)
Applies the given utilities to an element's ::after pseudo-element. Sugar over when("&::after", input).
aria(attribute: string, input: UtilityInput) / aria(attribute: string, value: string | number, input: UtilityInput)
Sugar over when(...) for an element's aria-* attribute selector: two args match the attribute present with any value — including "false" — while three args match a value exactly; pass "true" for the truthy case.
backdrop(input: UtilityInput)
Applies the given utilities to a top-layer element's ::backdrop, the layer the browser paints behind a <dialog> or popover to dim the page with no overlay, z-index, or scroll container; pairs with u.open().
before(input: UtilityInput)
Applies the given utilities to an element's ::before pseudo-element. Sugar over when("&::before", input).
checked(input: UtilityInput)
Sugar over when('&:checked, &[aria-checked="true"]', input), matching both native checked controls and ARIA-checked custom widgets.
data(attribute: string, input: UtilityInput) / data(attribute: string, value: string | number, input: UtilityInput)
Sugar over an element's own data-* attribute selector: matches &[data-{attribute}] (any value, including a bare boolean attribute) with no value argument, or &[data-{attribute}="{value}"] with one.
detailsContent(input: UtilityInput)
Applies the given utilities to a <details> element's ::details-content pseudo-element, the region holding everything after the <summary>. Combine with u.open()'s selector to scope styles to the open state.
disabled(input: UtilityInput)
Sugar over when('&:disabled, &[aria-disabled="true"]', input), applying the given utilities under both the native and ARIA disabled selectors. Callers choose the actual colors, opacity, and cursor for that state.
focusVisible(input: UtilityInput)
Sugar over when("&:focus-visible", input).
focusWithin(input: UtilityInput)
Sugar over when("&:focus-within", input).
has(selector: string, input: UtilityInput)
Sugar over when("&:has({selector})", input). Styles an element by its own descendants' state; :has() takes the specificity of its heaviest argument, so a complex selector here can outweigh overriding declarations.
hasSibling(selector: string, input: UtilityInput)
Sugar over when("&:has(~ {selector})", input), styling an element by a sibling's state. ~ matches only following siblings, so the indicator must come before the source input in the DOM.
hover(input: UtilityInput)
Sugar over when("&:hover", input).
indeterminate(input: UtilityInput)
Matches indeterminate checkboxes and ARIA mixed-state widgets, painting a third visual state; it also matches radios in an unselected group and valueless <progress>, so scope it to the control you mean.
invalid(input: UtilityInput)
Waits for user interaction before flagging a field invalid, matching :user-invalid alongside the ARIA fallback so validation only surfaces once it is meaningful to the person filling in the field.
marker(input: UtilityInput)
Applies the given utilities to a list item's marker or a <summary> disclosure triangle via ::marker; only color, font-*, and content apply. Use u.listStyle("none") to remove the marker along with its space.
not(selector: string, input: UtilityInput)
A selector wrapper for negated state: wraps selector in :not(...) and applies the given utilities there.
open(input: UtilityInput)
Sugar over when("&[open], &:popover-open", input), matching both the <details>/<dialog> open attribute and the Popover API's :popover-open pseudo-class.
placeholder(input: UtilityInput)
Styles an input or textarea's ::placeholder text. Give the field a real <label> too, since placeholder text vanishes on input and often renders at low contrast; style the empty input itself with u.placeholderShown().
placeholderShown(input: UtilityInput)
Sugar over when("&:placeholder-shown", input), matching an input or textarea while it is empty and therefore still showing its placeholder. Enables the float-label pattern with no JavaScript, paired with u.has().
precededBy(selector: string, input: UtilityInput)
Sugar over when(":is({selector}) ~ &", input), styling an element by a preceding sibling's state; the counterpart of hasSibling().
readOnly(input: UtilityInput)
Sugar over when('&:read-only, &[aria-readonly="true"]', input), matching native and ARIA read-only controls. They stay focusable and keep submitting their value with the form, so give them a flat, normal-but-static style.
required(input: UtilityInput)
Sugar over when('&:required, &[aria-required="true"]', input), matching required controls and widgets. Add a textual cue in the label too, since colour and a bare asterisk alone only reach sighted users.
selection(input: UtilityInput)
Applies utilities to the element's ::selection; only color, background-color, text-decoration, and text-shadow take effect, and overriding the platform's contrast guarantee requires a high-contrast pair.
when(selector: string, input: UtilityInput)
Nests input under selector; every other state wrapper (hover(), checked(), ...) is sugar over it. selector starts with &, @, :, [ or .; any other selector is dropped with a console warning.
where(selector: string, input: UtilityInput)
Sugar over when("& :where({selector})", input), targeting descendants of the host. :where() always contributes zero specificity, so the resulting rule stays overridable by any later single-class rule.
Responsive
at(size: ContainerName | string, input: UtilityInput) / at(size: ContainerName | string, name: string, input: UtilityInput)
Applies input while the nearest container, or the container called name, is at least size wide. size is a Containers step ("md") or a raw length.
atMax(size: ContainerName | string, input: UtilityInput) / atMax(size: ContainerName | string, name: string, input: UtilityInput)
The max-width counterpart to at: applies while the nearest container's inline size is at most size. Shares at's named-scale/literal-length resolution and named-container targeting.
atQuery(query: string, input: UtilityInput)
The raw escape hatch for expressing a container condition directly — querying height, orientation, a style feature, or combining several with and/or. query is used verbatim as the full @container condition.
contrastLess(input: UtilityInput)
Sugar over media("(prefers-contrast: less)", input). Browser support for this query lags behind contrastMore, so keep a base declaration alongside it to cover browsers that ignore the query.
contrastMore(input: UtilityInput)
Sugar over media("(prefers-contrast: more)", input). The theme layer already strengthens every tone's border here; reach for this wrapper to strengthen other properties, like a muted foreground.
dark(input: UtilityInput)
Sugar over scheme("dark", input).
forcedColors(input: UtilityInput)
Sugar over media("(forced-colors: active)", input). Forced-colors mode swaps colors for a system palette — use this to restore non-color cues like borders, or keep an element's own colors via forced-color-adjust.
light(input: UtilityInput)
Sugar over scheme("light", input).
media(query: string, input: UtilityInput)
The explicit escape hatch for a real viewport/feature media query, for a rule that must read the viewport or a user preference. u.at() handles container-based responsive layout.
motionReduce(input: UtilityInput)
Sugar over media("(prefers-reduced-motion: reduce)", input). Prefer u.motionSafe() when there is a choice: declaring motion only inside the positive query lets a missing wrapper fall back to no motion.
motionSafe(input: UtilityInput)
Sugar over media("(prefers-reduced-motion: no-preference)", input). Styles apply only when the user has not asked for less motion, so a missing wrapper safely defaults to no animation.
print(input: UtilityInput)
Sugar over `media("
