# 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.

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

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.

## 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:

```tsx
<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:

```tsx
<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:

```tsx
<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:

```tsx
<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:

```tsx
<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:

```tsx
<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.

```ts
u.hover(u.bg())
```

## Responsive design

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

```ts
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:

```css
: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);
}
```

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

The new name is then accepted wherever the scale is:

```ts
bg("info")
```

## Signature

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