---
title: "color"
description: "The color namespace — the engine's Luau API reference for color."
section: "API Reference"
slug: "api-color"
canonical: "https://origozero.ai/docs/api-color"
updated: "2026-09-05T23:13:46.284702893+00:00"
tags: ["api", "reference"]
---

# color

The `color` namespace — 67 functions.

## globals/color/coerce {#globals-color-coerce}

```lua
color.coerce(value: any?) -> Color?
```

Read a value written in any of the shapes a colour is authored
in — a hex string, an `{r=,g=,b=,a=}` map, or an `{r,g,b,a}` array
— as an sRGB color table. Returns `nil` when the value does not
describe a colour, so a caller can name the value it was handed
instead of substituting one. Channels absent from a map or array
read as 0; alpha absent reads as 1.

**Parameters**

- `value` `any` _(optional)_ — Value to read as a colour.

**Returns** `Color?` — sRGB color table, or `nil` when `value` is not a colour.

```lua
local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })
```

## globals/color/complementary {#globals-color-complementary}

```lua
color.complementary(c: Color) -> Color
```

Complementary color — rotate hue 180° in Oklch space.

**Parameters**

- `c` `Color` — Input color.

**Returns** `Color` — Complementary sRGB color.

```lua
local accent = color.complementary(primary)
```

## globals/color/darken {#globals-color-darken}

```lua
color.darken(c: Color, amount: number) -> Color
```

Decrease the lightness of a color in Oklch perceptual space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Lightness decrease 0-1.

**Returns** `Color` — Darkened sRGB color.

```lua
local pressed = color.darken(base, 0.1)
```

## globals/color/desaturate {#globals-color-desaturate}

```lua
color.desaturate(c: Color, amount: number) -> Color
```

Decrease the chroma (saturation) of a color in Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Chroma decrease (typically 0-0.2).

**Returns** `Color` — Less saturated sRGB color.

```lua
local muted = color.desaturate(base, 0.05)
```

## globals/color/hex {#globals-color-hex}

```lua
color.hex(hexString: string) -> Color?
```

Parse a hex color string into an sRGB color table. Accepts 3,
4, 6, or 8 hex digits with or without a leading `#` (e.g. "#f00",
"f00f", "#ff0000", "ff000080"). Returns `nil` on parse failure.

**Parameters**

- `hexString` `string` — Hex color string.

**Returns** `Color?` — sRGB color table or `nil`.

```lua
local fromCss = color.hex("#ff8800")
```

## globals/color/hsl {#globals-color-hsl}

```lua
color.hsl(h: number, s: number, l: number) -> Color
```

Build a color from HSL (`h: 0-360`, `s: 0-1`, `l: 0-1`).
Returned as sRGB.

**Parameters**

- `h` `number` — Hue (degrees, 0-360).
- `s` `number` — Saturation (0-1).
- `l` `number` — Lightness (0-1).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`.

```lua
local teal = color.hsl(180, 0.5, 0.5)
```

## globals/color/hsla {#globals-color-hsla}

```lua
color.hsla(h: number, s: number, l: number, a: number) -> Color
```

Build a color from HSLA, returned as sRGB.

**Parameters**

- `h` `number` — Hue (0-360).
- `s` `number` — Saturation (0-1).
- `l` `number` — Lightness (0-1).
- `a` `number` — Alpha (0-1).

**Returns** `Color` — sRGB color table `{ r, g, b, a }`.

```lua
local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)
```

## globals/color/hsv {#globals-color-hsv}

```lua
color.hsv(h: number, s: number, v: number) -> Color
```

Build a color from HSV (`h: 0-360`, `s: 0-1`, `v: 0-1`).

**Parameters**

- `h` `number` — Hue (0-360).
- `s` `number` — Saturation (0-1).
- `v` `number` — Value / brightness (0-1).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`.

```lua
local primary = color.hsv(220, 0.7, 0.9)
```

## globals/color/lighten {#globals-color-lighten}

```lua
color.lighten(c: Color, amount: number) -> Color
```

Increase the lightness of a color in Oklch perceptual space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Lightness increase 0-1.

**Returns** `Color` — Lightened sRGB color.

```lua
local hover = color.lighten(base, 0.1)
```

## globals/color/linear {#globals-color-linear}

```lua
color.linear(r: number, g: number, b: number, a: number?) -> Color
```

Build a color from linear RGB values (not gamma-corrected),
output converted to sRGB. Useful for GPU-correct blending. Alpha
defaults to 1.

**Parameters**

- `r` `number` — Linear red (0-1).
- `g` `number` — Linear green (0-1).
- `b` `number` — Linear blue (0-1).
- `a` `number` _(optional)_ — Alpha (0-1, default 1).

**Returns** `Color` — sRGB color table `{ r, g, b, a }`.

```lua
local gpuBlue = color.linear(0.0, 0.0, 1.0)
```

## globals/color/mix {#globals-color-mix}

```lua
color.mix(c1: Color, c2: Color, t: number) -> Color
```

Perceptually blend two colors in Oklch space — better than RGB
mixing for gradients.

**Parameters**

- `c1` `Color` — First color.
- `c2` `Color` — Second color.
- `t` `number` — Blend factor 0-1 (0 = c1, 1 = c2).

**Returns** `Color` — Blended sRGB color.

```lua
local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)
```

## globals/color/mixRgb {#globals-color-mixrgb}

```lua
color.mixRgb(c1: Color, c2: Color, t: number) -> Color
```

Linearly blend two colors in sRGB space — simple, but not
perceptually uniform. Prefer `color.mix` for natural gradients.

**Parameters**

- `c1` `Color` — First color.
- `c2` `Color` — Second color.
- `t` `number` — Blend factor 0-1.

**Returns** `Color` — Blended sRGB color.

```lua
local plain = color.mixRgb(a, b, 0.5)
```

## globals/color/oklch {#globals-color-oklch}

```lua
color.oklch(l: number, c: number, h: number) -> Color
```

Build a color from Oklch perceptual color space (`l: 0-1`,
`c: 0-0.4`, `h: 0-360`). Ideal for perceptually uniform gradients
and color manipulation.

**Parameters**

- `l` `number` — Lightness (0-1).
- `c` `number` — Chroma / saturation (0-0.4).
- `h` `number` — Hue (0-360).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`.

```lua
local accent = color.oklch(0.7, 0.15, 30)
```

## globals/color/rgb {#globals-color-rgb}

```lua
color.rgb(r: number, g: number, b: number) -> Color
```

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha
defaults to 1. Channels are normalised to 0-1 on the way out so
the result composes with every other color helper.

**Parameters**

- `r` `number` — Red channel (0-255).
- `g` `number` — Green channel (0-255).
- `b` `number` — Blue channel (0-255).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`, normalised to 0-1.

```lua
local red = color.rgb(255, 0, 0)
```

## globals/color/rgba {#globals-color-rgba}

```lua
color.rgba(r: number, g: number, b: number, a: number) -> Color
```

Build an sRGB color from CSS-style 0-255 RGB channels with
explicit alpha. RGB are normalised to 0-1; alpha is taken as-is
in the 0-1 range.

**Parameters**

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

**Returns** `Color` — sRGB color table `{ r, g, b, a }`.

```lua
local halfRed = color.rgba(255, 0, 0, 0.5)
```

## globals/color/rotateHue {#globals-color-rotatehue}

```lua
color.rotateHue(c: Color, degrees: number) -> Color
```

Rotate the hue of a color by a given number of degrees in
Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `degrees` `number` — Hue rotation (positive or negative).

**Returns** `Color` — Hue-rotated sRGB color.

```lua
local triadic = color.rotateHue(base, 120)
```

## globals/color/saturate {#globals-color-saturate}

```lua
color.saturate(c: Color, amount: number) -> Color
```

Increase the chroma (saturation) of a color in Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Chroma increase (typically 0-0.2).

**Returns** `Color` — More saturated sRGB color.

```lua
local pop = color.saturate(base, 0.05)
```

## globals/color/toHex {#globals-color-tohex}

```lua
color.toHex(c: Color) -> string
```

Convert a color to a hex string. Returns `"#rrggbb"` or
`"#rrggbbaa"` if alpha is not 1.

**Parameters**

- `c` `Color` — Input color.

**Returns** `string` — Hex color string.

```lua
print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"
```

## globals/color/toHsl {#globals-color-tohsl}

```lua
color.toHsl(c: Color) -> HslColor
```

Convert a color to HSL.

**Parameters**

- `c` `Color` — Input color.

**Returns** `HslColor` — HSL color table `{ h, s, l, a }` (h: 0-360, s/l: 0-1).

```lua
local hsl = color.toHsl(base)
```

## globals/color/toLinear {#globals-color-tolinear}

```lua
color.toLinear(c: Color) -> Color
```

Convert a color from sRGB to linear RGB space — useful for GPU
calculations that need linear-space values.

**Parameters**

- `c` `Color` — Input sRGB color.

**Returns** `Color` — Linear RGB color table.

```lua
local gpu = color.toLinear(base)
```

## globals/color/toOklch {#globals-color-tooklch}

```lua
color.toOklch(c: Color) -> OklchColor
```

Convert a color to Oklch perceptual color space.

**Parameters**

- `c` `Color` — Input color.

**Returns** `OklchColor` — Oklch color table `{ l, c, h, a }` (l: 0-1, c: 0-0.4, h: 0-360).

```lua
local okl = color.toOklch(base)
```

## globals/color/withAlpha {#globals-color-withalpha}

```lua
color.withAlpha(c: Color, a: number) -> Color
```

Return a copy of a color with a different alpha value.

**Parameters**

- `c` `Color` — Input color.
- `a` `number` — New alpha (0-1).

**Returns** Color with modified alpha.

```lua
local ghost = color.withAlpha(base, 0.3)
```

## modules/color/README {#modules-color-readme}

```lua
require("@builtin/modules/api/engine/color") -- color (also available as global 'color')
```

Color construction, conversion, and perceptual ops (RGB / HSL / HSV / Oklch / hex). Public Luau surface over the `__color` Internal FFI namespace.

Usage: local color = require("@builtin/modules/api/engine/color")
Also available as global: color

## modules/color/coerce {#modules-color-coerce}

```lua
coerce(value: any): Color?
```

Read a value written in any of the shapes a colour is authored
in — a hex string, an `{r=,g=,b=,a=}` map, or an `{r,g,b,a}` array
— as an sRGB color table. Returns `nil` when the value does not
describe a colour, so a caller can name the value it was handed
instead of substituting one. Channels absent from a map or array
read as 0; alpha absent reads as 1.

**Parameters**

- `value` `any` _(optional)_ — Value to read as a colour.

```lua
local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })
```

## modules/color/complementary {#modules-color-complementary}

```lua
complementary(c: Color): Color
```

Complementary color — rotate hue 180° in Oklch space.

**Parameters**

- `c` `Color` — Input color.

```lua
local accent = color.complementary(primary)
```

## modules/color/darken {#modules-color-darken}

```lua
darken(c: Color, amount: number): Color
```

Decrease the lightness of a color in Oklch perceptual space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Lightness decrease 0-1.

```lua
local pressed = color.darken(base, 0.1)
```

## modules/color/desaturate {#modules-color-desaturate}

```lua
desaturate(c: Color, amount: number): Color
```

Decrease the chroma (saturation) of a color in Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Chroma decrease (typically 0-0.2).

```lua
local muted = color.desaturate(base, 0.05)
```

## modules/color/hex {#modules-color-hex}

```lua
hex(hexString: string): Color?
```

Parse a hex color string into an sRGB color table. Accepts 3,
4, 6, or 8 hex digits with or without a leading `#` (e.g. "#f00",
"f00f", "#ff0000", "ff000080"). Returns `nil` on parse failure.

**Parameters**

- `hexString` `string` — Hex color string.

```lua
local fromCss = color.hex("#ff8800")
```

## modules/color/hsl {#modules-color-hsl}

```lua
hsl(h: number, s: number, l: number): Color
```

Build a color from HSL (`h: 0-360`, `s: 0-1`, `l: 0-1`).
Returned as sRGB.

**Parameters**

- `h` `number` — Hue (degrees, 0-360).
- `s` `number` — Saturation (0-1).
- `l` `number` — Lightness (0-1).

```lua
local teal = color.hsl(180, 0.5, 0.5)
```

## modules/color/hsla {#modules-color-hsla}

```lua
hsla(h: number, s: number, l: number, a: number): Color
```

Build a color from HSLA, returned as sRGB.

**Parameters**

- `h` `number` — Hue (0-360).
- `s` `number` — Saturation (0-1).
- `l` `number` — Lightness (0-1).
- `a` `number` — Alpha (0-1).

```lua
local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)
```

## modules/color/hsv {#modules-color-hsv}

```lua
hsv(h: number, s: number, v: number): Color
```

Build a color from HSV (`h: 0-360`, `s: 0-1`, `v: 0-1`).

**Parameters**

- `h` `number` — Hue (0-360).
- `s` `number` — Saturation (0-1).
- `v` `number` — Value / brightness (0-1).

```lua
local primary = color.hsv(220, 0.7, 0.9)
```

## modules/color/lighten {#modules-color-lighten}

```lua
lighten(c: Color, amount: number): Color
```

Increase the lightness of a color in Oklch perceptual space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Lightness increase 0-1.

```lua
local hover = color.lighten(base, 0.1)
```

## modules/color/linear {#modules-color-linear}

```lua
linear(r: number, g: number, b: number, a: number?): Color
```

Build a color from linear RGB values (not gamma-corrected),
output converted to sRGB. Useful for GPU-correct blending. Alpha
defaults to 1.

**Parameters**

- `r` `number` — Linear red (0-1).
- `g` `number` — Linear green (0-1).
- `b` `number` — Linear blue (0-1).
- `a` `number?` _(optional)_ — Alpha (0-1, default 1).

```lua
local gpuBlue = color.linear(0.0, 0.0, 1.0)
```

## modules/color/mix {#modules-color-mix}

```lua
mix(c1: Color, c2: Color, t: number): Color
```

Perceptually blend two colors in Oklch space — better than RGB
mixing for gradients.

**Parameters**

- `c1` `Color` — First color.
- `c2` `Color` — Second color.
- `t` `number` — Blend factor 0-1 (0 = c1, 1 = c2).

```lua
local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)
```

## modules/color/mixRgb {#modules-color-mixrgb}

```lua
mixRgb(c1: Color, c2: Color, t: number): Color
```

Linearly blend two colors in sRGB space — simple, but not
perceptually uniform. Prefer `color.mix` for natural gradients.

**Parameters**

- `c1` `Color` — First color.
- `c2` `Color` — Second color.
- `t` `number` — Blend factor 0-1.

```lua
local plain = color.mixRgb(a, b, 0.5)
```

## modules/color/oklch {#modules-color-oklch}

```lua
oklch(l: number, c: number, h: number): Color
```

Build a color from Oklch perceptual color space (`l: 0-1`,
`c: 0-0.4`, `h: 0-360`). Ideal for perceptually uniform gradients
and color manipulation.

**Parameters**

- `l` `number` — Lightness (0-1).
- `c` `number` — Chroma / saturation (0-0.4).
- `h` `number` — Hue (0-360).

```lua
local accent = color.oklch(0.7, 0.15, 30)
```

## modules/color/rgb {#modules-color-rgb}

```lua
rgb(r: number, g: number, b: number): Color
```

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha
defaults to 1. Channels are normalised to 0-1 on the way out so
the result composes with every other color helper.

**Parameters**

- `r` `number` — Red channel (0-255).
- `g` `number` — Green channel (0-255).
- `b` `number` — Blue channel (0-255).

```lua
local red = color.rgb(255, 0, 0)
```

## modules/color/rgba {#modules-color-rgba}

```lua
rgba(r: number, g: number, b: number, a: number): Color
```

Build an sRGB color from CSS-style 0-255 RGB channels with
explicit alpha. RGB are normalised to 0-1; alpha is taken as-is
in the 0-1 range.

**Parameters**

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

```lua
local halfRed = color.rgba(255, 0, 0, 0.5)
```

## modules/color/rotateHue {#modules-color-rotatehue}

```lua
rotateHue(c: Color, degrees: number): Color
```

Rotate the hue of a color by a given number of degrees in
Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `degrees` `number` — Hue rotation (positive or negative).

```lua
local triadic = color.rotateHue(base, 120)
```

## modules/color/saturate {#modules-color-saturate}

```lua
saturate(c: Color, amount: number): Color
```

Increase the chroma (saturation) of a color in Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Chroma increase (typically 0-0.2).

```lua
local pop = color.saturate(base, 0.05)
```

## modules/color/toHex {#modules-color-tohex}

```lua
toHex(c: Color): string
```

Convert a color to a hex string. Returns `"#rrggbb"` or
`"#rrggbbaa"` if alpha is not 1.

**Parameters**

- `c` `Color` — Input color.

```lua
print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"
```

## modules/color/toHsl {#modules-color-tohsl}

```lua
toHsl(c: Color): HslColor
```

Convert a color to HSL.

**Parameters**

- `c` `Color` — Input color.

```lua
local hsl = color.toHsl(base)
```

## modules/color/toLinear {#modules-color-tolinear}

```lua
toLinear(c: Color): Color
```

Convert a color from sRGB to linear RGB space — useful for GPU
calculations that need linear-space values.

**Parameters**

- `c` `Color` — Input sRGB color.

```lua
local gpu = color.toLinear(base)
```

## modules/color/toOklch {#modules-color-tooklch}

```lua
toOklch(c: Color): OklchColor
```

Convert a color to Oklch perceptual color space.

**Parameters**

- `c` `Color` — Input color.

```lua
local okl = color.toOklch(base)
```

## modules/color/withAlpha {#modules-color-withalpha}

```lua
withAlpha(c: Color, a: number): Color
```

Return a copy of a color with a different alpha value.

**Parameters**

- `c` `Color` — Input color.
- `a` `number` — New alpha (0-1).

```lua
local ghost = color.withAlpha(base, 0.3)
```

## typed/builtin//modules/api/engine/color/color/coerce {#typed-builtin-modules-api-engine-color-color-coerce}

```lua
color.coerce(value: any?) -> Color?
```

Read a value written in any of the shapes a colour is authored
in — a hex string, an `{r=,g=,b=,a=}` map, or an `{r,g,b,a}` array
— as an sRGB color table. Returns `nil` when the value does not
describe a colour, so a caller can name the value it was handed
instead of substituting one. Channels absent from a map or array
read as 0; alpha absent reads as 1.

**Parameters**

- `value` `any` _(optional)_ — Value to read as a colour.

**Returns** `Color?` — sRGB color table, or `nil` when `value` is not a colour.

```lua
local c = color.coerce("#5a5a62") or color.coerce({ 0.2, 0.7, 0.2 })
```

## typed/builtin//modules/api/engine/color/color/complementary {#typed-builtin-modules-api-engine-color-color-complementary}

```lua
color.complementary(c: Color) -> Color
```

Complementary color — rotate hue 180° in Oklch space.

**Parameters**

- `c` `Color` — Input color.

**Returns** `Color` — Complementary sRGB color.

```lua
local accent = color.complementary(primary)
```

## typed/builtin//modules/api/engine/color/color/darken {#typed-builtin-modules-api-engine-color-color-darken}

```lua
color.darken(c: Color, amount: number) -> Color
```

Decrease the lightness of a color in Oklch perceptual space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Lightness decrease 0-1.

**Returns** `Color` — Darkened sRGB color.

```lua
local pressed = color.darken(base, 0.1)
```

## typed/builtin//modules/api/engine/color/color/desaturate {#typed-builtin-modules-api-engine-color-color-desaturate}

```lua
color.desaturate(c: Color, amount: number) -> Color
```

Decrease the chroma (saturation) of a color in Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Chroma decrease (typically 0-0.2).

**Returns** `Color` — Less saturated sRGB color.

```lua
local muted = color.desaturate(base, 0.05)
```

## typed/builtin//modules/api/engine/color/color/hex {#typed-builtin-modules-api-engine-color-color-hex}

```lua
color.hex(hexString: string) -> Color?
```

Parse a hex color string into an sRGB color table. Accepts 3,
4, 6, or 8 hex digits with or without a leading `#` (e.g. "#f00",
"f00f", "#ff0000", "ff000080"). Returns `nil` on parse failure.

**Parameters**

- `hexString` `string` — Hex color string.

**Returns** `Color?` — sRGB color table or `nil`.

```lua
local fromCss = color.hex("#ff8800")
```

## typed/builtin//modules/api/engine/color/color/hsl {#typed-builtin-modules-api-engine-color-color-hsl}

```lua
color.hsl(h: number, s: number, l: number) -> Color
```

Build a color from HSL (`h: 0-360`, `s: 0-1`, `l: 0-1`).
Returned as sRGB.

**Parameters**

- `h` `number` — Hue (degrees, 0-360).
- `s` `number` — Saturation (0-1).
- `l` `number` — Lightness (0-1).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`.

```lua
local teal = color.hsl(180, 0.5, 0.5)
```

## typed/builtin//modules/api/engine/color/color/hsla {#typed-builtin-modules-api-engine-color-color-hsla}

```lua
color.hsla(h: number, s: number, l: number, a: number) -> Color
```

Build a color from HSLA, returned as sRGB.

**Parameters**

- `h` `number` — Hue (0-360).
- `s` `number` — Saturation (0-1).
- `l` `number` — Lightness (0-1).
- `a` `number` — Alpha (0-1).

**Returns** `Color` — sRGB color table `{ r, g, b, a }`.

```lua
local fadedTeal = color.hsla(180, 0.5, 0.5, 0.3)
```

## typed/builtin//modules/api/engine/color/color/hsv {#typed-builtin-modules-api-engine-color-color-hsv}

```lua
color.hsv(h: number, s: number, v: number) -> Color
```

Build a color from HSV (`h: 0-360`, `s: 0-1`, `v: 0-1`).

**Parameters**

- `h` `number` — Hue (0-360).
- `s` `number` — Saturation (0-1).
- `v` `number` — Value / brightness (0-1).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`.

```lua
local primary = color.hsv(220, 0.7, 0.9)
```

## typed/builtin//modules/api/engine/color/color/lighten {#typed-builtin-modules-api-engine-color-color-lighten}

```lua
color.lighten(c: Color, amount: number) -> Color
```

Increase the lightness of a color in Oklch perceptual space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Lightness increase 0-1.

**Returns** `Color` — Lightened sRGB color.

```lua
local hover = color.lighten(base, 0.1)
```

## typed/builtin//modules/api/engine/color/color/linear {#typed-builtin-modules-api-engine-color-color-linear}

```lua
color.linear(r: number, g: number, b: number, a: number?) -> Color
```

Build a color from linear RGB values (not gamma-corrected),
output converted to sRGB. Useful for GPU-correct blending. Alpha
defaults to 1.

**Parameters**

- `r` `number` — Linear red (0-1).
- `g` `number` — Linear green (0-1).
- `b` `number` — Linear blue (0-1).
- `a` `number` _(optional)_ — Alpha (0-1, default 1).

**Returns** `Color` — sRGB color table `{ r, g, b, a }`.

```lua
local gpuBlue = color.linear(0.0, 0.0, 1.0)
```

## typed/builtin//modules/api/engine/color/color/mix {#typed-builtin-modules-api-engine-color-color-mix}

```lua
color.mix(c1: Color, c2: Color, t: number) -> Color
```

Perceptually blend two colors in Oklch space — better than RGB
mixing for gradients.

**Parameters**

- `c1` `Color` — First color.
- `c2` `Color` — Second color.
- `t` `number` — Blend factor 0-1 (0 = c1, 1 = c2).

**Returns** `Color` — Blended sRGB color.

```lua
local mid = color.mix(color.rgb(255, 0, 0), color.rgb(0, 0, 255), 0.5)
```

## typed/builtin//modules/api/engine/color/color/mixRgb {#typed-builtin-modules-api-engine-color-color-mixrgb}

```lua
color.mixRgb(c1: Color, c2: Color, t: number) -> Color
```

Linearly blend two colors in sRGB space — simple, but not
perceptually uniform. Prefer `color.mix` for natural gradients.

**Parameters**

- `c1` `Color` — First color.
- `c2` `Color` — Second color.
- `t` `number` — Blend factor 0-1.

**Returns** `Color` — Blended sRGB color.

```lua
local plain = color.mixRgb(a, b, 0.5)
```

## typed/builtin//modules/api/engine/color/color/oklch {#typed-builtin-modules-api-engine-color-color-oklch}

```lua
color.oklch(l: number, c: number, h: number) -> Color
```

Build a color from Oklch perceptual color space (`l: 0-1`,
`c: 0-0.4`, `h: 0-360`). Ideal for perceptually uniform gradients
and color manipulation.

**Parameters**

- `l` `number` — Lightness (0-1).
- `c` `number` — Chroma / saturation (0-0.4).
- `h` `number` — Hue (0-360).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`.

```lua
local accent = color.oklch(0.7, 0.15, 30)
```

## typed/builtin//modules/api/engine/color/color/rgb {#typed-builtin-modules-api-engine-color-color-rgb}

```lua
color.rgb(r: number, g: number, b: number) -> Color
```

Build an sRGB color from CSS-style 0-255 RGB channels. Alpha
defaults to 1. Channels are normalised to 0-1 on the way out so
the result composes with every other color helper.

**Parameters**

- `r` `number` — Red channel (0-255).
- `g` `number` — Green channel (0-255).
- `b` `number` — Blue channel (0-255).

**Returns** `Color` — sRGB color table `{ r, g, b, a = 1 }`, normalised to 0-1.

```lua
local red = color.rgb(255, 0, 0)
```

## typed/builtin//modules/api/engine/color/color/rgba {#typed-builtin-modules-api-engine-color-color-rgba}

```lua
color.rgba(r: number, g: number, b: number, a: number) -> Color
```

Build an sRGB color from CSS-style 0-255 RGB channels with
explicit alpha. RGB are normalised to 0-1; alpha is taken as-is
in the 0-1 range.

**Parameters**

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

**Returns** `Color` — sRGB color table `{ r, g, b, a }`.

```lua
local halfRed = color.rgba(255, 0, 0, 0.5)
```

## typed/builtin//modules/api/engine/color/color/rotateHue {#typed-builtin-modules-api-engine-color-color-rotatehue}

```lua
color.rotateHue(c: Color, degrees: number) -> Color
```

Rotate the hue of a color by a given number of degrees in
Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `degrees` `number` — Hue rotation (positive or negative).

**Returns** `Color` — Hue-rotated sRGB color.

```lua
local triadic = color.rotateHue(base, 120)
```

## typed/builtin//modules/api/engine/color/color/saturate {#typed-builtin-modules-api-engine-color-color-saturate}

```lua
color.saturate(c: Color, amount: number) -> Color
```

Increase the chroma (saturation) of a color in Oklch space.

**Parameters**

- `c` `Color` — Input color.
- `amount` `number` — Chroma increase (typically 0-0.2).

**Returns** `Color` — More saturated sRGB color.

```lua
local pop = color.saturate(base, 0.05)
```

## typed/builtin//modules/api/engine/color/color/toHex {#typed-builtin-modules-api-engine-color-color-tohex}

```lua
color.toHex(c: Color) -> string
```

Convert a color to a hex string. Returns `"#rrggbb"` or
`"#rrggbbaa"` if alpha is not 1.

**Parameters**

- `c` `Color` — Input color.

**Returns** `string` — Hex color string.

```lua
print(color.toHex(color.rgb(255, 136, 0))) -- "#ff8800"
```

## typed/builtin//modules/api/engine/color/color/toHsl {#typed-builtin-modules-api-engine-color-color-tohsl}

```lua
color.toHsl(c: Color) -> HslColor
```

Convert a color to HSL.

**Parameters**

- `c` `Color` — Input color.

**Returns** `HslColor` — HSL color table `{ h, s, l, a }` (h: 0-360, s/l: 0-1).

```lua
local hsl = color.toHsl(base)
```

## typed/builtin//modules/api/engine/color/color/toLinear {#typed-builtin-modules-api-engine-color-color-tolinear}

```lua
color.toLinear(c: Color) -> Color
```

Convert a color from sRGB to linear RGB space — useful for GPU
calculations that need linear-space values.

**Parameters**

- `c` `Color` — Input sRGB color.

**Returns** `Color` — Linear RGB color table.

```lua
local gpu = color.toLinear(base)
```

## typed/builtin//modules/api/engine/color/color/toOklch {#typed-builtin-modules-api-engine-color-color-tooklch}

```lua
color.toOklch(c: Color) -> OklchColor
```

Convert a color to Oklch perceptual color space.

**Parameters**

- `c` `Color` — Input color.

**Returns** `OklchColor` — Oklch color table `{ l, c, h, a }` (l: 0-1, c: 0-0.4, h: 0-360).

```lua
local okl = color.toOklch(base)
```

## typed/builtin//modules/api/engine/color/color/withAlpha {#typed-builtin-modules-api-engine-color-color-withalpha}

```lua
color.withAlpha(c: Color, a: number) -> Color
```

Return a copy of a color with a different alpha value.

**Parameters**

- `c` `Color` — Input color.
- `a` `number` — New alpha (0-1).

**Returns** Color with modified alpha.

```lua
local ghost = color.withAlpha(base, 0.3)
```