[ @sdxc/u/color ]

background-color

Applies background-color, or the full set of background properties when given an options object, of which only the given keys are set.

View as Markdown Open in GitHub Open in ChatGPT Open in Claude

import { bg } from "@sdxc/u/color";

Quick reference

Every documented call, beside the CSS it emits.

Call	CSS
`u.bg()`	`css({ backgroundColor: "var(--ui-bg, Canvas)" })`
`u.bg("brand.tint")`	`css({ backgroundColor: "var(--ui-brand-bg-tint)" })`
`u.bg({ image: "url(/hero.jpg)", size: "cover", position: "center" })`	`css({ backgroundImage: "url(/hero.jpg)", backgroundSize: "cover", backgroundPosition: "center" })`
`u.bg({ color: "brand.solid", clip: "content-box" })`	`css({ backgroundColor: "var(--ui-brand-bg-solid)", backgroundClip: "content-box" })`

Examples

Basic example

Use bg with a tone and its weight, like brand.tint or brand.solid, to set the background color of an element:

bg("brand.tint")

bg("brand.solid")

bg("neutral.tint")

<div mix={[...]}>
	<div mix={[bg("brand.tint"), fg("brand.emphasis"), ...]}>bg("brand.tint")</div>
	<div mix={[bg("brand.solid"), fg("brand.onSolid"), ...]}>bg("brand.solid")</div>
	<div mix={[bg("neutral.tint"), fg("neutral.emphasis"), ...]}>
		bg("neutral.tint")
	</div>
</div>

Tones

Every tone, brand, neutral, success, warning and danger, has a tint weight for quiet surfaces and a solid weight for emphasis:

bg("success.tint")

bg("success.solid")

bg("warning.tint")

bg("warning.solid")

bg("danger.tint")

bg("danger.solid")

<div mix={[...]}>
	<div mix={[bg("success.tint"), fg("success.emphasis"), ...]}>
		bg("success.tint")
	</div>
	<div mix={[bg("success.solid"), fg("success.onSolid"), ...]}>
		bg("success.solid")
	</div>
	<div mix={[bg("warning.tint"), fg("warning.emphasis"), ...]}>
		bg("warning.tint")
	</div>
	<div mix={[bg("warning.solid"), fg("warning.onSolid"), ...]}>
		bg("warning.solid")
	</div>
	<div mix={[bg("danger.tint"), fg("danger.emphasis"), ...]}>bg("danger.tint")</div>
	<div mix={[bg("danger.solid"), fg("danger.onSolid"), ...]}>bg("danger.solid")</div>
</div>

Palette shades

Reach past the tones to a palette shade, written color.<palette>.<shade> like color.brand.300, when no tone names the color you need:

100

300

500

700

900

<div mix={[...]}>
	<div mix={[bg("color.brand.100"), fg("color.brand.900"), ...]}>100</div>
	<div mix={[bg("color.brand.300"), fg("color.brand.900"), ...]}>300</div>
	<div mix={[bg("color.brand.500"), fg("color.brand.50"), ...]}>500</div>
	<div mix={[bg("color.brand.700"), fg("color.brand.50"), ...]}>700</div>
	<div mix={[bg("color.brand.900"), fg("color.brand.100"), ...]}>900</div>
</div>

Arbitrary colors

Pass a CSS color function, like oklch() or one built with colorMix, and it is used as written:

bg("oklch(0.72 0.16 160)")

bg(colorMix(...))

<div mix={[...]}>
	<div mix={[bg("oklch(0.72 0.16 160)"), fg("color.neutral.950"), ...]}>
		bg("oklch(0.72 0.16 160)")
	</div>
	<div
		mix={[
			bg(colorMix("oklab", "var(--ui-brand-bg-solid) 40%", "transparent")),
			fg(),
			...,
		]}
	>
		bg(colorMix(...))
	</div>
</div>

Background images

Pass an object to set the background image, size, position and repeat together; only the keys you give are set:

image, size and repeat

<div
	mix={[
		bg({
			color: "brand.tint",
			image: radialGradient("circle", "var(--ui-brand-border-strong) 2px", "transparent 2.5px"),
			size: "1rem 1rem",
			position: "center",
			repeat: "repeat",
		}),
		fg("brand.emphasis"),
		is(64),
		bs(32),
		...,
	]}
>
	image, size and repeat
</div>

Background clip

Set clip to keep the background off the border or the padding; with content-box the padding stays unpainted:

border-box

padding-box

content-box

<div mix={[...]}>
	<div
		mix={[
			bg({ color: "brand.solid", clip: "border-box" }),
			border({ color: "brand.strong", width: 4, style: "dashed" }),
			p(4),
			fg("brand.onSolid"),
			...,
		]}
	>
		border-box
	</div>
	<div
		mix={[
			bg({ color: "brand.solid", clip: "padding-box" }),
			border({ color: "brand.strong", width: 4, style: "dashed" }),
			p(4),
			fg("brand.onSolid"),
			...,
		]}
	>
		padding-box
	</div>
	<div
		mix={[
			bg({ color: "brand.solid", clip: "content-box" }),
			border({ color: "brand.strong", width: 4, style: "dashed" }),
			p(4),
			fg("brand.onSolid"),
			...,
		]}
	>
		content-box
	</div>
</div>

Applying on a state

Wrap the call in a state utility to scope it to one selector.

u.hover(u.bg())

Responsive design

Wrap the call in a container query to scope it to one width.

u.at("md", u.bg())

Customizing your theme

Customizing colors

Define a palette as --ui-color-{name}-{50..950} and map a tone onto it with the --ui-{tone}-* variables, the way theme.css maps the built-in ones:

:root {
	--ui-color-info-50: oklch(0.97 0.02 230);
	--ui-color-info-200: oklch(0.88 0.06 230);
	--ui-color-info-500: oklch(0.62 0.16 230);
	--ui-color-info-600: oklch(0.52 0.18 230);
	--ui-color-info-900: oklch(0.3 0.1 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-muted: var(--ui-color-info-500);
	--ui-info-fg-emphasis: var(--ui-color-info-900);
	--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);
}

declare module "@sdxc/u" {
	interface ColorPalettes {
		info: true;
	}
	interface SemanticTones {
		info: true;
	}
}

The new name is then accepted wherever the scale is:

bg("info")

Signature

u.bg(value?: ColorValue | (string & {}))