# Color foundations
> What @sdxc/ui/color is for, the native-control and labelling rules its parts share, and every variable it reads.

Color inputs: swatches, a swatch picker, a saturation area, a hue wheel, channel sliders, a validated field and a popover picker.

Each is a native control underneath, so it submits with a form and works by keyboard before script loads.

Import the components from `@sdxc/ui/color` and the theme once from `@sdxc/ui/theme.css`.

## When to reach for it

- A brand, accent or theme color setting in a form.
- Labels, tags or calendars a user colors from a preset palette.
- A design tool or editor that needs every channel, alpha included.

## Shared ideas

- **Native controls.** Area, wheel and sliders are `<input type="range">`; the swatch picker is radios.
- **Labels required.** `ColorWheel`, `ColorArea` and `ColorPicker.Trigger` warn in development without an accessible name.
- **Targets.** Slider inputs and swatch options grow to `--ui-target-size`, 44px on a coarse pointer.
- **Direction.** Gradients flip under `:dir(rtl)`; an area's vertical axis keeps low at the bottom.
- **Motion.** Thumb transitions are instant under `prefers-reduced-motion`.
- **Server first.** The server renders working controls; `colorWheelDrag()`, `colorAreaDrag()` and `colorPreview()` add gestures.

## CSS variables

Every custom property the namespace reads or declares. Reads the neutral role for borders, checkerboards and fills, and brand for focus rings, checked swatches and thumb borders. The roles are documented on Theming.

### Sizes

None is declared in `theme.css`; set any of them on the control or an ancestor.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-color-swatch-size-sm` | `1.25rem` | Size of a swatch with `size="sm"`. |
| `--ui-color-swatch-size-md` | `1.75rem` | Size of a swatch at the default size. |
| `--ui-color-swatch-size-lg` | `2.5rem` | Size of a swatch with `size="lg"`. |
| `--ui-color-swatch-checker-size` | `0.625rem` | Checkerboard cell behind a translucent swatch. |
| `--ui-color-picker-trigger-size` | `2.25rem` | Size of the button that opens a `ColorPicker`. |
| `--ui-color-area-size` | `16rem` | Width and height of a `ColorArea`. |
| `--ui-color-area-thumb-thickness` | `0.1875rem` | Width of the line each of the area's thumbs draws. |
| `--ui-color-wheel-size` | `12rem` | Diameter of a round `ColorWheel`. |
| `--ui-color-wheel-thumb-size` | `1.25rem` | Wheel thumb size, the ring's thickness and the plain bar's height. |
| `--ui-color-wheel-thumb-border-width` | `2px` | Border of the wheel's thumb. |
| `--ui-color-slider-thumb-size` | `1.25rem` | `Slider` thumb size and the track's height. |
| `--ui-color-slider-thumb-border-width` | `2px` | Border of a slider's thumb. |
| `--ui-color-slider-checker-size` | `0.625rem` | Checkerboard cell behind an alpha track. |
| `--ui-target-size` | `1.5rem; 2.75rem on a coarse pointer` | Smallest pointer target a slider or swatch option keeps. |

### Shape and elevation

Read through `@sdxc/u`'s `rounded()` and `shadow()`; each default is the fallback an app overrides by declaring the variable.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-radius-none` | `0px` | Corners of a `shape="square"` swatch. |
| `--ui-radius-md` | `0.375rem` | Corners of an area, a rounded swatch and the picker's trigger. |
| `--ui-radius-full` | `9999px` | Corners of the wheel, slider tracks, thumbs and round swatches. |
| `--ui-shadow-base` | `0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)` | Lift under every thumb. |

### Set by the components

Written from a control's value or props, or by a mixin, and read back by its own parts. Leave them unset.

| Variable | Default | What it controls |
| --- | --- | --- |
| `--ui-color-swatch-value` | `set by ColorSwatch from value` | The color a swatch shows; `colorPreview()` rewrites it while typing. |
| `--ui-color-area-hue` | `set by ColorArea from hue` | Hue of the area's base layer. |
| `--ui-color-wheel-hue, --ui-color-wheel-value` | `set by ColorWheel from its value` | Angle the thumb turns to and the hue its border shows. |
| `--ui-color-slider-hue` | `set by ColorSlider.Track from hue` | Hue a saturation, lightness or alpha gradient is painted at. |
| `--ui-color-wheel-track-direction, --ui-color-slider-track-direction` | `right; left in right-to-left text` | Direction a hue bar's or slider's gradient runs. |
| `--ui-color-slider-channel-<channel>` | `written by channelSync()` | Each sibling channel's value, for a custom track gradient to read. |