# theme/color (zidane-ui)

Import: `import { … } from 'zidane-ui'`. Source: [ui/src/theme/color.ts](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts).

## Functions

### `capChroma`

Function.

Return `color` with chroma capped at `max`.

```ts
function capChroma(color: string, max: number): string
```

**Parameters**

- `color` (`string`): The CSS color.
- `max` (`number`): The highest chroma to keep.

**Returns** `string`

Source: [ui/src/theme/color.ts:381](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L381)

### `contrastRatio`

Function.

WCAG 2.x contrast ratio, 1..21.

```ts
function contrastRatio(a: string | Rgb, b: string | Rgb): number
```

**Parameters**

- `a` (`string | Rgb`): The first color.
- `b` (`string | Rgb`): The second color.

**Returns** `number`

Source: [ui/src/theme/color.ts:309](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L309)

### `ensureContrast`

Function.

Nudge `fg` lightness away from `bg` until `contrastRatio(fg, bg) >= min`,
keeping hue/chroma. Returns the first passing color, or the extreme
(white / black by surface luminance) when the hue can't reach the target.

```ts
function ensureContrast(fg: string, bg: string, min: number): string
```

**Parameters**

- `fg` (`string`): The foreground color to adjust.
- `bg` (`string`): The background it sits on.
- `min` (`number`): The contrast ratio to reach.

**Returns** `string`

Source: [ui/src/theme/color.ts:414](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L414)

### `formatColor`

Function.

Formats a color as CSS: `#rrggbb`, or `rgba()` when alpha is below 1.

```ts
function formatColor(c: Rgb): string
```

**Parameters**

- `c` (`Rgb`): The color to format.

**Returns** `string`: The CSS color string.

Source: [ui/src/theme/color.ts:123](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L123)

### `isDark`

Function.

Tells whether a surface color is dark enough that white text reads better than black.

```ts
function isDark(color: string): boolean
```

**Parameters**

- `color` (`string`): The CSS color of the surface.

**Returns** `boolean`: `true` when its luminance is below [`DARK_LUMINANCE_THRESHOLD`](https://zidane.si/docs/reference/ui-theme-color.md#DARK_LUMINANCE_THRESHOLD).

Source: [ui/src/theme/color.ts:329](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L329)

### `luminance`

Function.

WCAG relative luminance, 0 (black) .. 1 (white). Alpha is ignored.

```ts
function luminance(color: string | Rgb): number
```

**Parameters**

- `color` (`string | Rgb`): A CSS color string or an sRGB color. An unparseable string counts as black.

**Returns** `number`

Source: [ui/src/theme/color.ts:295](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L295)

### `mix`

Function.

Perceptual mix in OKLab. `t = 0` → a, `t = 1` → b. Alpha is mixed linearly.

```ts
function mix(a: string, b: string, t: number): string
```

**Parameters**

- `a` (`string`): The color at `t = 0`. Returned when either color cannot be parsed.
- `b` (`string`): The color at `t = 1`.
- `t` (`number`): How far from `a` to `b`, clamped to 0..1.

**Returns** `string`

Source: [ui/src/theme/color.ts:344](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L344)

### `oklch`

Function.

Convenience: parse → OKLCH → format, for terse palette code.

```ts
function oklch(l: number, c: number, h: number, a?: number): string
```

**Parameters**

- `l` (`number`): Lightness, 0..1.
- `c` (`number`): Chroma, 0..\~0.4.
- `h` (`number`): Hue in degrees.
- `a?` (`number`, default `1`): Alpha, 0..1.

**Returns** `string`: The CSS color string, gamut-mapped to sRGB.

Source: [ui/src/theme/color.ts:145](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L145)

### `oklchToRgb`

Function.

OKLCH → sRGB with gamut mapping: if the color is out of gamut, chroma is
reduced (binary search) until it fits. Lightness and hue are preserved,
which is what you want when deriving ramps: a too-vivid accent becomes
the most vivid *displayable* version of itself instead of clipping to a
different hue.

```ts
function oklchToRgb(c: Oklch): Rgb
```

**Parameters**

- `c` (`Oklch`): The OKLCH color.

**Returns** `Rgb`: The sRGB color, clamped to 0..1.

Source: [ui/src/theme/color.ts:241](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L241)

### `parseColor`

Function.

Parses a CSS color into sRGB. It accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()`,
`rgba()` and `oklch()`; an OKLCH color out of gamut is chroma-reduced to fit.

```ts
function parseColor(input: string): Rgb | undefined
```

**Parameters**

- `input` (`string`): The color string.

**Returns** `Rgb | undefined`: The color, or `undefined` when the string is not a supported color.

Source: [ui/src/theme/color.ts:49](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L49)

### `readableOn`

Function.

Pick a readable foreground for `bg`: `preferred` if it already passes
`min`, else `preferred` pushed until it does, else pure white/black.

```ts
function readableOn(bg: string, preferred: string, min?: number): string
```

**Parameters**

- `bg` (`string`): The background color.
- `preferred` (`string`): The foreground to use when it is readable.
- `min?` (`number`, default `4.5`): The contrast ratio to reach. Defaults to 4.5.

**Returns** `string`

Source: [ui/src/theme/color.ts:448](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L448)

### `rgbToOklch`

Function.

Converts an sRGB color to OKLCH. Near-gray colors get a chroma and hue of 0.

```ts
function rgbToOklch(c: Rgb): Oklch
```

**Parameters**

- `c` (`Rgb`): The sRGB color.

**Returns** `Oklch`: The OKLCH color.

Source: [ui/src/theme/color.ts:221](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L221)

### `tintedNeutral`

Function.

Build a color of the given lightness that carries a faint tint of `hue`
source, the "neutral with personality" every good editor theme uses
instead of pure gray. Chroma is `tint`, clamped to what stays subtle.

```ts
function tintedNeutral(l: number, tintSource: string, tint: number): string
```

**Parameters**

- `l` (`number`): Lightness, 0..1.
- `tintSource` (`string`): The color whose hue the neutral carries. Without a parseable one the result
  is pure gray.
- `tint` (`number`): The chroma of the tint, clamped to 0..0.06.

**Returns** `string`

Source: [ui/src/theme/color.ts:399](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L399)

### `toOklch`

Function.

Parses a CSS color and converts it to OKLCH.

```ts
function toOklch(color: string): Oklch | undefined
```

**Parameters**

- `color` (`string`): The CSS color string.

**Returns** `Oklch | undefined`: The OKLCH color, or `undefined` when the string cannot be parsed.

Source: [ui/src/theme/color.ts:281](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L281)

### `withAlpha`

Function.

Returns `color` with its alpha replaced.

```ts
function withAlpha(color: string, alpha: number): string
```

**Parameters**

- `color` (`string`): The CSS color. Returned unchanged when it cannot be parsed.
- `alpha` (`number`): The new alpha, clamped to 0..1.

**Returns** `string`: The CSS color string.

Source: [ui/src/theme/color.ts:156](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L156)

### `withLightness`

Function.

Return `color` with lightness set (0..1), chroma/hue preserved (gamut-mapped).

```ts
function withLightness(color: string, l: number): string
```

**Parameters**

- `color` (`string`): The CSS color.
- `l` (`number`): The new lightness, 0..1.

**Returns** `string`

Source: [ui/src/theme/color.ts:367](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L367)

## Constants

### `DARK_LUMINANCE_THRESHOLD`

Constant.

Threshold under which a surface is "dark" for the purpose of picking a
white vs black foreground. 0.179 is the point where white and black text
have equal WCAG contrast against the surface.

```ts
const DARK_LUMINANCE_THRESHOLD = 0.179
```

Source: [ui/src/theme/color.ts:321](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L321)

## Interfaces

### `Oklch`

Interface.

A color in OKLCH: perceptual lightness, chroma and hue, plus alpha.

```ts
interface Oklch
```

**Properties**

- `a` (`number`): Alpha, 0..1
- `c` (`number`): Chroma, 0..\~0.4
- `h` (`number`): Hue in degrees, 0..360
- `l` (`number`): Lightness, 0..1

Source: [ui/src/theme/color.ts:25](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L25)

### `Rgb`

Interface.

A color in sRGB, every channel from 0 to 1.

```ts
interface Rgb
```

**Properties**

- `a` (`number`): Alpha, 0..1
- `b` (`number`): Blue channel, 0..1
- `g` (`number`): Green channel, 0..1
- `r` (`number`): Red channel, 0..1

Source: [ui/src/theme/color.ts:13](https://github.com/Tahul/zidane/blob/main/ui/src/theme/color.ts#L13)