# border-color

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

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

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.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.border()` | `css({ borderColor: "var(--ui-border, color-mix(in oklab, CanvasText 16%, transparent))" })` |
| `u.border("brand.strong")` | `css({ borderColor: "var(--ui-brand-border-strong)" })` |
| `u.border({ color: "brand", width: 2 })` | `css({ borderColor: "var(--ui-brand-border)", borderWidth: "2px", borderStyle: "solid" })` |
| `u.border({ width: 2, noStyleDefault: true })` | `css({ borderWidth: "2px" })` |
| `u.border("none")` | `css({ border: "none" })` |

## Examples

### Basic example

Use `border` with an object to set the width, color and style of an element's border together; the style defaults to `solid`:

```tsx
<div mix={[...]}>
	<div mix={[border({ color: "neutral.strong", width: 1 }), ...]}>width: 1</div>
	<div mix={[border({ color: "neutral.strong", width: 2 }), ...]}>width: 2</div>
	<div mix={[border({ color: "neutral.strong", width: 4 }), ...]}>width: 4</div>
</div>
```

### Border color

Pass a string to set only the color: a bare tone like `brand` reads its subtle border weight, and `brand.strong` its strong one:

```tsx
<div mix={[...]}>
	<div mix={[border({ width: 2 }), border("brand"), ...]}>border("brand")</div>
	<div mix={[border({ width: 2 }), border("brand.strong"), ...]}>
		border("brand.strong")
	</div>
	<div mix={[border({ width: 2 }), border("danger.strong"), ...]}>
		border("danger.strong")
	</div>
	<div mix={[border({ width: 2 }), border("color.warning.400"), ...]}>
		border("color.warning.400")
	</div>
</div>
```

### Border style

Set `style` to draw a dashed, dotted or double border:

```tsx
<div mix={[...]}>
	<div mix={[border({ color: "brand.strong", width: 2, style: "dashed" }), ...]}>
		dashed
	</div>
	<div mix={[border({ color: "brand.strong", width: 2, style: "dotted" }), ...]}>
		dotted
	</div>
	<div mix={[border({ color: "brand.strong", width: 4, style: "double" }), ...]}>
		double
	</div>
</div>
```

### Removing a border

Pass `none` to remove a border entirely, such as the one a browser draws around a native button:

```tsx
<div mix={[...]}>
	<button type="button" mix={[...]}>
		Default button
	</button>
	<button type="button" mix={[border("none"), ...]}>
		border("none")
	</button>
</div>
```

## Applying on a state

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

```ts
u.hover(u.border())
```

## Responsive design

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

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

## 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
border("info")
```

## Signature

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