# outline

> Applies an outline unconditionally, for a persistent or decorative edge.

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

Applies an outline unconditionally, for a persistent or decorative edge. A
bare string is a color, a bare number is a width in pixels, the two together
set both, and an options object sets every property at once.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.outline()` | `css({ outlineColor: "var(--ui-ring, Highlight)", outlineWidth: "2px", outlineStyle: "solid" })` |
| `u.outline("danger")` | `css({ outlineColor: "var(--ui-danger-ring)", outlineWidth: "2px", outlineStyle: "solid" })` |
| `u.outline(4)` | `css({ outlineColor: "var(--ui-ring, Highlight)", outlineWidth: "4px", outlineStyle: "solid" })` |
| `u.outline("danger", 4)` | `css({ outlineColor: "var(--ui-danger-ring)", outlineWidth: "4px", outlineStyle: "solid" })` |
| `u.outline({ color: "danger", offset: 4 })` | `css({ outlineColor: "var(--ui-danger-ring)", outlineWidth: "2px", outlineStyle: "solid", outlineOffset: "4px" })` |
| `u.outline("none")` | `css({ outline: "none" })` |

## Examples

### Basic example

Use `outline()` to draw an outline around an element; pass a tone to color it, or a number to set its width in pixels:

```tsx
<div mix={[...]}>
	<div mix={[outline(), ...]}>outline()</div>
	<div mix={[outline("success"), ...]}>outline("success")</div>
	<div mix={[outline(4), ...]}>outline(4)</div>
</div>
```

### Color and width

Pass a tone and a width together, like `danger` and `4`, to set both at once:

```tsx
<div mix={[...]}>
	<div mix={[outline("danger", 4), ...]}>outline("danger", 4)</div>
	<div mix={[outline("warning", 6), ...]}>outline("warning", 6)</div>
</div>
```

### Offset

Pass an object with `offset` to leave a gap between the outline and the element:

```tsx
<div mix={[...]}>
	<div mix={[outline({ color: "brand", offset: 0 }), ...]}>offset: 0</div>
	<div mix={[outline({ color: "brand", offset: 4 }), ...]}>offset: 4</div>
	<div mix={[outline({ color: "brand", offset: 8 }), ...]}>offset: 8</div>
</div>
```

### Style

Set `style` in the object to draw a dashed, dotted or double outline:

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

## Applying on a state

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

```ts
u.hover(u.outline())
```

## Responsive design

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

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

## 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.outline()
```