# surface

> Composes `u.bg()`, `u.fg()`, and `u.border()` so a surface's contrast holds by construction.

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

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.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.surface()` | `css({ backgroundColor: "var(--ui-bg, Canvas)", color: "var(--ui-fg, CanvasText)", borderColor: "var(--ui-border, ...)" })` |
| `u.surface("brand.tinted")` | `css({ backgroundColor: "var(--ui-brand-bg-tint)", color: "var(--ui-brand-fg-emphasis)", borderColor: "var(--ui-brand-border)" })` |
| `u.surface("danger")` | `css({ backgroundColor: "var(--ui-danger-bg-solid)", color: "var(--ui-danger-fg-on-solid)", borderColor: "var(--ui-danger-bg-solid)" })` |

## Examples

### Basic example

Use `surface()` to set the background, text and border colors of an element as one matching set:

```tsx
<div mix={[surface(), border({ width: 1 }), rounded("lg"), p(6)]}>
	<p mix={[...]}>surface() paints the page's own background, text and border.</p>
</div>
```

### Muted and tinted surfaces

Use the `muted` recipe for a quiet panel, or a tone with `.tinted`, like `brand.tinted`, for a tinted callout:

```tsx
<div mix={[...]}>
	<div mix={[surface("muted"), border({ width: 1 }), ...]}>surface("muted")</div>
	<div mix={[surface("brand.tinted"), border({ width: 1 }), ...]}>
		surface("brand.tinted")
	</div>
	<div mix={[surface("danger.tinted"), border({ width: 1 }), ...]}>
		surface("danger.tinted")
	</div>
</div>
```

### Solid surfaces

Pass a bare tone, like `brand`, for a solid surface whose text color is chosen to read on it:

```tsx
<div mix={[...]}>
	<div mix={[surface("brand"), border({ width: 1 }), ...]}>surface("brand")</div>
	<div mix={[surface("success"), border({ width: 1 }), ...]}>surface("success")</div>
	<div mix={[surface("warning"), border({ width: 1 }), ...]}>surface("warning")</div>
	<div mix={[surface("danger"), border({ width: 1 }), ...]}>surface("danger")</div>
</div>
```

## Applying on a state

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

```ts
u.hover(u.surface())
```

## Responsive design

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

```ts
u.at("md", u.surface())
```

## 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.surface(recipe?: SurfaceRecipe)
```