# ringShadow

> Draws a selection ring that stays visible for as long as a component applies it, for persistently-selected swatches, chips, and thumbnails.

```ts
import { ringShadow } from "@sdxc/u/effects";
```

Draws a selection ring that stays visible for as long as a component applies
it, for persistently-selected swatches, chips, and thumbnails. Occupies the
composite `boxShadow` `ring` slot, painting inside `u.shadow()`'s elevation.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.ringShadow("brand")` | `css({ "--ui-box-shadow-ring": "0 0 0 2px var(--ui-brand-bg-solid)", boxShadow: "var(--ui-box-shadow-ring, 0 0 #0000), var(--ui-box-shadow-elevation, 0 0 #0000)" })` |
| `u.ringShadow("danger", 3)` | `css({ "--ui-box-shadow-ring": "0 0 0 3px var(--ui-danger-bg-solid)", boxShadow: "var(--ui-box-shadow-ring, 0 0 #0000), var(--ui-box-shadow-elevation, 0 0 #0000)" })` |

## Examples

### Basic example

Use `ringShadow(tone)` to draw a solid ring around an element, like a persistently selected thumbnail:

```tsx
<div mix={[...]}>
	<div mix={[...]}>
		<img mix={[ringShadow("brand"), ...]} src={...} alt="" />
		<span mix={[...]}>ringShadow("brand")</span>
	</div>
	<div mix={[...]}>
		<img mix={[ringShadow("success"), ...]} src={...} alt="" />
		<span mix={[...]}>ringShadow("success")</span>
	</div>
	<div mix={[...]}>
		<img mix={[ringShadow("danger"), ...]} src={...} alt="" />
		<span mix={[...]}>ringShadow("danger")</span>
	</div>
</div>
```

### Changing the width

Pass a width as the second argument, in pixels or any CSS length; it's `2` by default:

```tsx
<div mix={[...]}>
	<div mix={[...]}>
		<img mix={[ringShadow("brand", 1), ...]} src={...} alt="" />
		<span mix={[...]}>ringShadow("brand", 1)</span>
	</div>
	<div mix={[...]}>
		<img mix={[ringShadow("brand", 4), ...]} src={...} alt="" />
		<span mix={[...]}>ringShadow("brand", 4)</span>
	</div>
	<div mix={[...]}>
		<img mix={[ringShadow("brand", "0.5rem"), ...]} src={...} alt="" />
		<span mix={[...]}>ringShadow("brand", "0.5rem")</span>
	</div>
</div>
```

### Combining with a shadow

The ring and `shadow()` write separate layers of one `box-shadow`, so an element can have both:

```tsx
<div mix={[ringShadow("brand"), shadow("xl"), ...]}>Selected plan</div>
```

### Marking the selected option

Combine it with `has(":checked", …)` to ring the option whose radio is checked. Pick an option:

```tsx
<div mix={[...]}>
	<label mix={[has(":checked", ringShadow("brand")), ...]}>
		<input type="radio" name="plan" checked /> Monthly
	</label>
	<label mix={[has(":checked", ringShadow("brand")), ...]}>
		<input type="radio" name="plan" /> Yearly
	</label>
</div>
```

## Applying on a state

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

```ts
u.hover(u.ringShadow("brand"))
```

## Responsive design

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

```ts
u.at("md", u.ringShadow("brand"))
```

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

## Signature

```ts
u.ringShadow(value: ColorValue | (string & {}), width?: number | (string & {}))
```