# @sdxc/u Utility-first styling for `remix/ui`, composed from small, terse mixins. Every export is a `remix/ui` mixin factory that drops straight into a `mix` prop, and the wrappers compose with any other utility to build responsive, stateful styles: ```tsx
``` The utilities cover CSS primitives across thirteen families, plus composed patterns like `u.surface()` and `u.hstack()`. Logical properties are the default, each with a physical counterpart for the values that must not flip with writing mode. ## Installation ```bash npm add @sdxc/u ``` Every utility returns a `remix/ui` mixin, so [`remix`](https://www.npmjs.com/package/remix) installs alongside this package. ## Usage ### Import ```tsx import * as u from "@sdxc/u";
; ``` Every utility is also a named export, and every family has its own subpath, so a call site can pick exactly how much it imports: ```tsx import { bg, p } from "@sdxc/u"; import { bg } from "@sdxc/u/color"; import { p } from "@sdxc/u/size"; import bg from "@sdxc/u/color/bg"; import p from "@sdxc/u/size/p"; ``` The pure token resolvers live at their own `@sdxc/u/tokens` subpath rather than the package root, because four of them share a name with a utility mixin (`font`, `text`, `shadow`, `blur`). Importing from `@sdxc/u/tokens` always gets the resolver; importing from the root always gets the mixin: ```ts import { blur, spacing } from "@sdxc/u/tokens"; spacing(4); // "calc(var(--ui-spacing, 0.25rem) * 4)" blur("sm"); // "var(--ui-blur-sm, 4px)" ``` ### Import the theme ```css @import "@sdxc/u/theme.css"; /* your app's styles */ ``` `theme.css` defines the semantic tone layer (`--ui-{tone}-bg-tint`, `--ui-{tone}-fg`, ...) for `neutral`, `brand`, `success`, `warning`, and `danger`, plus the spacing, container-breakpoint, font, and text-size scale variables. It does **not** define the raw palette scale — an app defines `--ui-color-{name}-{50..950}` itself: ```css :root { --ui-color-neutral-50: oklch(0.985 0 0); --ui-color-neutral-100: oklch(0.97 0 0); /* ...through 950 */ --ui-color-brand-50: oklch(0.97 0.02 250); --ui-color-brand-600: oklch(0.52 0.18 250); /* ...through 950 */ } ``` Add `.dark` to an ancestor (typically ``) for forced dark mode, or `.system` to follow `prefers-color-scheme` instead. ### Extending the token names Every named token family — color palettes, semantic tones, radii, text sizes, font families, container breakpoints, shadows, blurs — is a TypeScript interface an app extends through declaration merging, backed by nothing but the matching `--ui-*` variable: ```ts declare module "@sdxc/u" { interface ColorPalettes { info: true; } interface SemanticTones { info: true; } } ``` ```css :root { --ui-color-info-50: hsl(...); --ui-color-info-600: hsl(...); /* ... */ --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); /* ... */ } ``` No runtime registry backs any of this — a utility resolves a token name straight to `var(--ui-*)` at call time. ## API Every function below returns a `UtilityMixin`: a real `remix/ui` host-element mixin, valid directly in a `mix` prop, that also carries a hidden style tree wrapper utilities (`u.hover()`, `u.at()`, `u.media()`, ...) can read and re-nest. Anywhere a parameter is typed `UtilityInput`, it accepts a single `UtilityMixin`, a falsy value (dropped), or a (possibly nested) array of the same. ### General #### `calc(expression: string): string` Wraps an arithmetic expression in CSS's `calc(...)`. A plain string resolver, not a mixin — use it anywhere a utility accepts a raw CSS value, most often paired with `u.var()` so a custom property can be offset, negated, or scaled at the call site instead of being redefined. **Parameters:** - `expression`: The arithmetic expression to wrap, written exactly as CSS expects it. Passed through untouched — nothing is validated or normalized, so CSS's own rule that `+` and `-` must be surrounded by spaces is the call site's responsibility (`"100% - 1rem"` is valid, `"100%-1rem"` is not). **Returns:** - The resolved `calc(...)` string **Example:** ```typescript let result = u.calc("100% - 1rem"); // "calc(100% - 1rem)" let negatedResult = u.calc(`${u.var("arrow-offset", "0.5rem")} * -1`); // "calc(var(--arrow-offset, 0.5rem) * -1)" ``` Since it returns a string rather than a mixin, it goes wherever a raw CSS length is accepted: ```tsx
``` #### `combine(input: UtilityInput): UtilityMixin` Flattens `input` and merges the flattened utilities' style trees into one, with no wrapping selector or at-rule — the identity case of `u.when()`'s merge-then-nest primitive. This is not the same as listing the same utilities in a `mix` array: a `mix` array keeps each utility separate and leaves conflicts to the cascade, while `combine()` merges them at call time, left to right, into one declaration set. A later declaration overwrites an earlier one, but nested blocks sharing a selector key merge recursively instead of replacing each other. Reach for it when something needs to hand out one mixin rather than a list — every wrapper utility already accepts nested arrays, so `combine()` is about producing a single value, not about satisfying a wrapper. **Parameters:** - `input`: One utility mixin, or a (possibly nested) array of them, falsy values dropped **Returns:** - A `UtilityMixin` carrying the merged declarations of every utility in `input` **CSS:** ```css /* u.combine([u.rounded("lg"), u.border({ color: "neutral", width: 1 })]) */ .host { border-radius: var(--ui-radius-lg, 0.5rem); border-color: var(--ui-neutral-border); border-width: 1px; border-style: solid; } ``` **Example:** ```typescript let result = u.combine([u.rounded("lg"), u.border({ color: "neutral", width: 1 })]); // Nested branches merge as siblings rather than one replacing the other let statesResult = u.combine([ u.when("&:hover", u.bg("brand.tint")), u.when("&:focus", u.bg("brand.tint")), ]); ``` #### `counterIncrement(name: string, value?: number): UtilityMixin` Applies `counter-increment`, advancing the CSS counter identified by `name`. A CSS counter is a document-level integer created by `u.counterReset()` on an ancestor, advanced by this utility on each item, and read back through a `counter(name)` call inside a `content` value — so it pairs with `u.pseudoContent()` to number things CSS has no automatic numbering for. `name` is the counter's own identifier, not a custom property, so it is given bare with no `--` prefix. **Parameters:** - `name`: The counter identifier, without a `--` prefix - `value`: The integer to increment by. Omit it and no value is emitted at all, leaving CSS's own default of `1` in effect. Negative values count down. **Returns:** - A `UtilityMixin` that sets `counter-increment` **CSS:** ```css /* u.counterIncrement("section") */ .host { counter-increment: section; } /* u.counterIncrement("section", 2) */ .host { counter-increment: section 2; } ``` **Example:** ```typescript let result = u.counterIncrement("section"); let stepResult = u.counterIncrement("section", 2); let countdownResult = u.counterIncrement("remaining", -1); ``` The counter only renders once something reads it back — the full three-utility composition: ```tsx
  1. First step
``` #### `counterReset(name: string, value?: number): UtilityMixin` Applies `counter-reset`, creating (or resetting) the CSS counter identified by `name` on the host. This is the declaring half of the counter pair — put it on the ancestor that scopes the numbering, and `u.counterIncrement()` on each item inside it. Without it, an incremented counter has no scope to belong to. **Parameters:** - `name`: The counter identifier, without a `--` prefix - `value`: The integer to start the counter at. Omit it and no value is emitted at all, leaving CSS's own default of `0` in effect — so the first `u.counterIncrement()` of `1` produces `1`. Pass a value to start the numbering elsewhere. **Returns:** - A `UtilityMixin` that sets `counter-reset` **CSS:** ```css /* u.counterReset("section") */ .host { counter-reset: section; } /* u.counterReset("section", 10) */ .host { counter-reset: section 10; } ``` **Example:** ```typescript let result = u.counterReset("section"); let offsetResult = u.counterReset("section", 10); ``` #### `cursor(value: CursorValue | (string & {})): UtilityMixin` Applies `cursor`, the pointer affordance shown over the host. Most useful for the cases the platform guesses wrong: a `
` acting as a control needs `"pointer"` spelled out, and a `
{description}
``` #### `appearance(value?: AppearanceValue | (string & {}), options?: AppearanceOptions): UtilityMixin` A primitive form-control reset: it clears (or restores) the platform's native control chrome. By default the value is mirrored onto `-webkit-appearance` and `-moz-appearance` as well as the standard property, because Safari and Firefox both still need their own prefixed property to fully clear a ``, ``, or range ``'s native rendering. It only _removes_ the native look; it supplies no replacement. That is deliberate — the visual recipe belongs to the app or component — but it means a bare `u.appearance()` on a ` {options} ``` #### `basis(value?: SizeValue): UtilityMixin` Applies `flex-basis` — the size a flex item is laid out from before any free space is distributed. Together with `u.grow()` and `u.shrink()` it breaks the `flex` shorthand into three separately composable calls, so a call site sets only the part it means. It only does something on a flex item: the host has to be a direct child of a flex container (`u.flex()`, `u.inlineFlex()`, `u.hstack()`, `u.vstack()`), and it is ignored entirely on a grid or block child. Two things overwrite it. `u.spacer()` sets the whole `flex` shorthand (`1 1 auto`), whose third component _is_ `flex-basis`, so putting both on one element leaves the result to declaration order — pick one. And in a row direction `flex-basis` competes with `u.is()`: `flex-basis` wins over `inline-size` on a flex item, so an unexpected `basis` is the usual reason an explicit width appears to be ignored. **Parameters:** - `value`: The basis length. Defaults to `"auto"`, matching `flex-basis`'s own initial value, which sizes the item from its `inline-size`/content instead. - a `number` — resolved against the spacing scale as `calc(var(--ui-spacing, 0.25rem) * n)` - `"auto"` (the default) — passes through; the item is sized from its own width/content - `"full"` — resolved to `100%` - any other string — a raw CSS escape hatch, passed through unchanged (`"0%"`, `"13px"`, `"60ch"`, `"100dvh"`, a `var(...)`/`calc(...)` reference) **Returns:** - A `UtilityMixin` applying the `flex-basis` property. **CSS:** ```css /* u.basis() */ .host { flex-basis: auto; } /* u.basis(4) */ .host { flex-basis: calc(var(--ui-spacing, 0.25rem) * 4); } /* u.basis("0%") */ .host { flex-basis: 0%; } ``` **Example:** ```typescript let result = u.basis(); let scaleResult = u.basis(4); let fullResult = u.basis("full"); let rawResult = u.basis("0%"); ``` ```tsx
``` #### `block(): UtilityMixin` Sets `display: block`, making the host a block-level box that fills its container's inline axis and stacks with its siblings. Its most common real use is on a replaced or inline element that should stop sitting on the text baseline — an `` is `inline` by default, which leaves a few pixels of descender space below it inside its container. `u.block()` removes that. **Returns:** - A `UtilityMixin` that sets `display: block` **CSS:** ```css /* u.block() */ .host { display: block; } ``` **Example:** ```typescript let result = u.block(); ``` ```tsx ``` It conflicts with every other display utility, and with `u.lineClamp()`, which sets `display: -webkit-box` itself. #### `borderCollapse(value?: BorderCollapseValue): UtilityMixin` Controls whether a table's adjacent cell borders merge into single shared lines or each keep their own. Defaults to `"collapse"`, the common case of a table whose borders should read as one grid instead of doubling up along every shared edge. It only applies to a table box (a ``, or an element with a `table` display), and it decides whether `u.borderSpacing()` has any effect at all: under `"collapse"` the spacing between cells is ignored by definition. **Parameters:** - `value`: The collapsing model. Defaults to `"collapse"`. - `"collapse"` (the default) — adjacent cells share one border; the winning border is picked by CSS's border-conflict rules, so a per-cell border may lose to a neighbour's - `"separate"` — every cell draws its own border, and `border-spacing` applies between them **Returns:** - A `UtilityMixin` applying the `border-collapse` property. **CSS:** ```css /* u.borderCollapse() */ .host { border-collapse: collapse; } /* u.borderCollapse("separate") */ .host { border-collapse: separate; } ``` **Example:** ```typescript let result = u.borderCollapse(); let separateResult = u.borderCollapse("separate"); ``` ```tsx
``` #### `borderSpacing(value: string): UtilityMixin` Sets the gap between adjacent table cell borders. It has no effect unless `border-collapse: separate` is in force, so it is always paired with `u.borderCollapse("separate")` on the same table. It takes a raw CSS string rather than the spacing scale, because the property carries its own one- and two-length grammar (both axes, or horizontal then vertical) that a single scale value can't express — pass a `calc(var(--ui-spacing, 0.25rem) * n)` string, or `u.var("ui-spacing")`, when the value should track the spacing scale. **Parameters:** - `value`: A raw `border-spacing` value. Required — there is no default and no scale resolution; whatever string is given is emitted verbatim. - one length (`"0.5rem"`) — applies to both the horizontal and vertical gaps - two lengths separated by a space (`"0.5rem 1rem"`) — horizontal then vertical - any CSS length form works, including `var(...)` and `calc(...)` references **Returns:** - A `UtilityMixin` applying the `border-spacing` property. **CSS:** ```css /* u.borderSpacing("0.5rem") */ .host { border-spacing: 0.5rem; } /* u.borderSpacing("0.5rem 1rem") */ .host { border-spacing: 0.5rem 1rem; } ``` **Example:** ```typescript let result = u.borderSpacing("0.5rem"); let axisResult = u.borderSpacing("0.5rem 1rem"); let scaleResult = u.borderSpacing(u.var("ui-spacing", "0.25rem")); ``` ```tsx
``` #### `boxSizing(value: BoxSizingValue): UtilityMixin` Controls whether a declared size includes padding and border or excludes them. It governs every sizing utility on the same element — `u.is()`, `u.bs()`, `u.minIs()`, `u.minBs()` and their raw-CSS equivalents — so it is the switch that decides whether `u.is("full")` plus `u.p(4)` stays inside its parent or overflows it by the padding. There is no default: the two keywords are opposite intents, so the call site always names one. **Parameters:** - `value`: The box model to size against. Required — no default. - `"border-box"` — padding and border are folded into the declared `inline-size`/`block-size`; the content box shrinks to make room - `"content-box"` — the declared size covers the content box only, with padding and border added outside it (the CSS default) **Returns:** - A `UtilityMixin` applying the `box-sizing` property. **CSS:** ```css /* u.boxSizing("border-box") */ .host { box-sizing: border-box; } /* u.boxSizing("content-box") */ .host { box-sizing: content-box; } ``` **Example:** ```typescript let result = u.boxSizing("border-box"); let contentResult = u.boxSizing("content-box"); ``` ```tsx
``` #### `center(): UtilityMixin` A zero-argument convenience pattern that centres content on both axes. Composes `u.flex()`, `u.items("center")`, and `u.justify("center")`, adding no declarations of its own. Because it makes the host a flex container, it centres the host's _children_ — it does not centre the host itself within its own parent. For that, reach for `u.mi("auto")` on the host, or `u.self("center")` inside a flex or grid parent. **Returns:** - A `UtilityMixin` that sets `display: flex`, `align-items: center`, and `justify-content: center` **CSS:** ```css /* u.center() */ .host { display: flex; align-items: center; justify-content: center; } ``` **Example:** ```typescript let result = u.center(); ``` The classic use — an icon centred in a square button: ```tsx ``` It conflicts with other display utilities and with any `u.items()`/`u.justify()` on the same element. #### `container(name: string, type?: ContainerTypeValue): UtilityMixin` Declares the host as a named container query context, so a descendant's `u.at(size, name, input)` (or `u.atMax()`) can target it by name instead of resolving to whichever container happens to be nearest. This is the declaring half of the container-query pair — `u.at()` is the querying half, comparing its `size` argument against the container's inline size — and a query with no matching container simply never matches, which is the usual reason an `at()` rule appears to do nothing. It writes the `container` shorthand, so `container-name` and `container-type` are always set together rather than one being left behind from an earlier rule; a second `u.container()` on the same element replaces both. **Parameters:** - `name`: The container name a descendant's query refers to. Required; emitted verbatim as the shorthand's first segment. - `type`: The containment type — the shorthand's second segment. Defaults to `"inline-size"`. - `"inline-size"` (the default) — the container's inline size is queryable, which is what a width-style breakpoint needs; the block axis stays content-sized - `"size"` — both axes are queryable, but the element's block size no longer depends on its content, so it collapses unless a block size is set (via `u.bs()`/`u.minBs()`) - `"normal"` — establishes a style container only; size queries such as `u.at()`'s will not match it **Returns:** - A `UtilityMixin` applying `container: "{name} / {type}"`. **CSS:** ```css /* u.container("sidebar") */ .host { container: sidebar / inline-size; } /* u.container("sidebar", "size") */ .host { container: sidebar / size; } ``` **Example:** ```typescript let result = u.container("sidebar"); let sizedResult = u.container("sidebar", "size"); let styleOnlyResult = u.container("sidebar", "normal"); ``` ```tsx ``` #### `content(value?: JustifyValue): UtilityMixin` Sets `align-content`, distributing the host's content _lines_ along the cross axis. It accepts the same keywords as `u.justify()`, including the short `between`/`around`/`evenly` forms, which are aliased to their `space-*` CSS equivalents. It only does anything when there is more than one line to distribute _and_ spare room on the cross axis: in a flex container that means `u.flexWrap()` must be on and the container must be taller than its wrapped lines. In a grid container it applies to the row tracks, where it is more often useful. A single-line flex container ignores it entirely — that is the usual reason it appears to do nothing, and `u.items()` is probably what was wanted. **Parameters:** - `value`: The distribution keyword. Defaults to `"start"`. - `"start"` — lines packed to the cross-axis start. The default. - `"center"` — lines packed to the centre - `"end"` — lines packed to the cross-axis end - `"between"` — aliased to `space-between`: first line flush to the start, last to the end, equal gaps between - `"around"` — aliased to `space-around`: equal space around each line, so edge gaps are half the inner gaps - `"evenly"` — aliased to `space-evenly`: every gap equal, including the edges **Returns:** - A `UtilityMixin` that sets `align-content` **CSS:** ```css /* u.content("between") */ .host { align-content: space-between; } /* u.content("center") */ .host { align-content: center; } ``` **Example:** ```typescript let result = u.content(); let betweenResult = u.content("between"); let centerResult = u.content("evenly"); ``` A wrapping flex container with room to spare, which is when it actually applies: ```tsx
{tags}
``` Reach for `u.place({ content })` to set `align-content` and `justify-content` together. #### `contents(): UtilityMixin` Sets `display: contents`, which removes the host's own box from layout so its children are laid out as if they were direct children of the host's parent. It is how a wrapper component can exist in the markup — for grouping, keys, or logic — without adding a layout box that would break the parent's flex or grid. Use it carefully. Because the box disappears, so does everything that box would have done: backgrounds, borders, padding, and any size on the host render nothing. There are also long-standing accessibility bugs where `display: contents` on an element with semantics (a `
    `, a `