# Color scales

Import from `@pibbl/core/viz`. Each continuous provider takes `id`, `domain`, `colors`, and
optional `children`. Domain and colors accept ordinary values or signals.

- `SequentialColorScale`: two finite domain values and two colors.
  `useSequentialColorScale(id): Signal<ResolvedSequentialColorScale>`.
- `DivergingColorScale`: three finite domain values (endpoint, center, endpoint)
  and three colors. `useDivergingColorScale(id): Signal<ResolvedDivergingColorScale>`.

A resolved mapping exposes frozen `domain`, `colors`, `stops`, and
`map(value: number): string`. `ColorScaleStop` is `{value: number, color: string}`.
Use actual resolved stops and map results to compose annotations with core Text
and shapes. No inversion, generic scale hook, or automatic legend is provided.

Colors are required `#RRGGBB` strings (case-insensitive input); output is canonical
lowercase `#rrggbb`. Interpolation is linear per **encoded sRGB channel**, rounded
to the nearest integer, with exact authored endpoint and center colors. It is not
linear-light or perceptually uniform interpolation. There is no default palette;
choose endpoints that suit the data and provide labels or shapes in addition to
color when distinctions matter. Named CSS colors, alpha, gradients, and other
color spaces are deliberately outside this mapping contract.

Sequential domains may ascend or descend, preserving endpoint-color association.
If both domain values are equal, every finite input maps to the channel midpoint.
Diverging domains must be strictly increasing or strictly decreasing around the
authored center; no symmetry is inferred. A center input maps to the exact center
color. Both families clamp finite out-of-domain inputs to endpoint colors;
extrapolation is not supported. Nonfinite inputs reject rather than returning an
unknown color. Providers validate lazily when the resolved mapping is read.

Invalid counts, colors, domain values, or diverging order throw TypeError or
RangeError. IDs must be nonempty strings or symbols. Each dedicated hook resolves
the nearest matching ID and rejects a different color family, absent provider,
or crossing a Layer boundary. Color IDs occupy a separate namespace from
positional scale IDs. Scopes are restored after traversal/failure; signals and
computed mapping lifetimes are mount-owned.

These providers allocate no drawing box, position, clipping, or event targets.
Place marks and annotations using ordinary layout and positional scales. Read a
mapping with `.get()` inside a component to subscribe to its domain/color changes;
retain the returned hook signal for stable provider identity.

## Threshold colors

`ThresholdColorScale` takes `id`, `thresholds`, `colors`, and optional `children`.
`useThresholdColorScale(id): Signal<ResolvedThresholdColorScale>` returns frozen
`thresholds`, `colors`, `bands`, and `map(value: number): string`. Thresholds and
colors accept signals. Boundaries must be finite and strictly increasing with no
duplicates; colors must contain exactly one more entry than boundaries.

Each frozen `ThresholdColorBand` has `lower: number | undefined`,
`upper: number | undefined`, and canonical `color: string`. Lower bounds are
inclusive and upper bounds exclusive: equality belongs to the next/upper bucket.
Undefined edges are unbounded. Empty thresholds with one color define a constant
mapping with one unbounded band. Nonfinite map inputs reject. This is threshold
classification, not quantization or distribution-derived quantiles. No data is
aggregated or sorted on the caller's behalf. The same context, palette, failure,
and ownership rules apply as for the continuous families.

[Minimal executable example](https://github.com/benlesh/pibbl/blob/main/docs/site/minimal/viz/colors.tsx)

## API details from source

<span id="api-SequentialColorScale"></span>

### SequentialColorScale

Provides an allocation-independent sequential color mapping.

```ts
SequentialColorScale: (props: SequentialColorScaleProps) => PibblNode
```

Related API: [SequentialColorScale](/reference/components/color-scales/), [SequentialColorScaleProps](/reference/components/color-scales/), [PibblNode](/reference/types/elements-components/#pibblnode).

#### Parameters

- **`props`** — Explicit domain, colors, identity, and children. See [SequentialColorScaleProps](/reference/components/color-scales/).

#### Returns

Descendant content.

[View source — packages/core/src/features/viz/lib/sequential-color-scale.ts:55](/source/packages/core/src/features/viz/lib/sequential-color-scale-ts/#L55)

<span id="api-useSequentialColorScale"></span>

### useSequentialColorScale

Reads the dedicated ancestor sequential mapping.

```ts
useSequentialColorScale: (id: ScaleId) => Signal<ResolvedSequentialColorScale>
```

Related API: [useSequentialColorScale](/reference/components/color-scales/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedSequentialColorScale](/reference/components/color-scales/).

#### Parameters

- **`id`** — Color-scale identity. See [ScaleId](/reference/components/scale/).

#### Returns

Shared readonly mapping signal. See [ResolvedSequentialColorScale](/reference/components/color-scales/).

[View source — packages/core/src/features/viz/lib/sequential-color-scale.ts:65](/source/packages/core/src/features/viz/lib/sequential-color-scale-ts/#L65)

<span id="api-DivergingColorScale"></span>

### DivergingColorScale

Provides an allocation-independent color mapping with an authored center.

```ts
DivergingColorScale: (props: DivergingColorScaleProps) => PibblNode
```

Related API: [DivergingColorScale](/reference/components/color-scales/), [DivergingColorScaleProps](/reference/components/color-scales/), [PibblNode](/reference/types/elements-components/#pibblnode).

#### Parameters

- **`props`** — Explicit domain, colors, identity, and children. See [DivergingColorScaleProps](/reference/components/color-scales/).

#### Returns

Descendant content.

[View source — packages/core/src/features/viz/lib/diverging-color-scale.ts:58](/source/packages/core/src/features/viz/lib/diverging-color-scale-ts/#L58)

<span id="api-useDivergingColorScale"></span>

### useDivergingColorScale

Reads the dedicated ancestor diverging mapping.

```ts
useDivergingColorScale: (id: ScaleId) => Signal<ResolvedDivergingColorScale>
```

Related API: [useDivergingColorScale](/reference/components/color-scales/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedDivergingColorScale](/reference/components/color-scales/).

#### Parameters

- **`id`** — Color-scale identity. See [ScaleId](/reference/components/scale/).

#### Returns

Shared readonly mapping signal. See [ResolvedDivergingColorScale](/reference/components/color-scales/).

[View source — packages/core/src/features/viz/lib/diverging-color-scale.ts:68](/source/packages/core/src/features/viz/lib/diverging-color-scale-ts/#L68)

<span id="api-ColorScaleStop"></span>

### ColorScaleStop

One authored domain/color association.

```ts
interface ColorScaleStop
```

Related API: [ColorScaleStop](/reference/components/color-scales/).

#### See also

[ResolvedSequentialColorScale](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/color-types.ts:4](/source/packages/core/src/features/viz/lib/color-types-ts/#L4)

#### Properties and methods

<span id="api-ColorScaleStop-value"></span>
<details>
<summary>value</summary>


```ts
readonly value: number
```

Numeric data value at the color stop.

[View source — packages/core/src/features/viz/lib/color-types.ts:5](/source/packages/core/src/features/viz/lib/color-types-ts/#L5)

</details>

<span id="api-ColorScaleStop-color"></span>
<details>
<summary>color</summary>


```ts
readonly color: string
```

Canonical lowercase six-digit hexadecimal sRGB color.

[View source — packages/core/src/features/viz/lib/color-types.ts:6](/source/packages/core/src/features/viz/lib/color-types-ts/#L6)

</details>

<span id="api-SequentialColorScaleProps"></span>

### SequentialColorScaleProps

Inputs for a dedicated sequential color provider.

```ts
interface SequentialColorScaleProps
```

Related API: [SequentialColorScaleProps](/reference/components/color-scales/).

#### See also

[ResolvedSequentialColorScale](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/color-types.ts:41](/source/packages/core/src/features/viz/lib/color-types-ts/#L41)

#### Properties and methods

<span id="api-SequentialColorScaleProps-id"></span>
<details>
<summary>id</summary>


```ts
readonly id: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Identity in the color-scale namespace. See ScaleId.

[View source — packages/core/src/features/viz/lib/color-types.ts:42](/source/packages/core/src/features/viz/lib/color-types-ts/#L42)

</details>

<span id="api-SequentialColorScaleProps-domain"></span>
<details>
<summary>domain</summary>


```ts
readonly domain: SignalValue<readonly [number, number]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Finite endpoints; equal endpoints map all finite inputs to the color midpoint.

[View source — packages/core/src/features/viz/lib/color-types.ts:43](/source/packages/core/src/features/viz/lib/color-types-ts/#L43)

</details>

<span id="api-SequentialColorScaleProps-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: SignalValue<readonly [string, string]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Required #RRGGBB endpoint colors. No default palette is chosen.

[View source — packages/core/src/features/viz/lib/color-types.ts:46](/source/packages/core/src/features/viz/lib/color-types-ts/#L46)

</details>

<span id="api-SequentialColorScaleProps-children"></span>
<details>
<summary>children (optional)</summary>


```ts
readonly children?: PibblNode
```

Related API: [PibblNode](/reference/types/elements-components/#pibblnode).

Descendants consuming the mapping. See PibblNode.

[View source — packages/core/src/features/viz/lib/color-types.ts:49](/source/packages/core/src/features/viz/lib/color-types-ts/#L49)

</details>

<span id="api-DivergingColorScaleProps"></span>

### DivergingColorScaleProps

Inputs for a dedicated diverging color provider.

```ts
interface DivergingColorScaleProps
```

Related API: [DivergingColorScaleProps](/reference/components/color-scales/).

#### See also

[ResolvedDivergingColorScale](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/color-types.ts:52](/source/packages/core/src/features/viz/lib/color-types-ts/#L52)

#### Properties and methods

<span id="api-DivergingColorScaleProps-id"></span>
<details>
<summary>id</summary>


```ts
readonly id: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Identity in the color-scale namespace. See ScaleId.

[View source — packages/core/src/features/viz/lib/color-types.ts:53](/source/packages/core/src/features/viz/lib/color-types-ts/#L53)

</details>

<span id="api-DivergingColorScaleProps-domain"></span>
<details>
<summary>domain</summary>


```ts
readonly domain: SignalValue<readonly [number, number, number]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Strictly increasing or decreasing finite endpoints and center.

[View source — packages/core/src/features/viz/lib/color-types.ts:54](/source/packages/core/src/features/viz/lib/color-types-ts/#L54)

</details>

<span id="api-DivergingColorScaleProps-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: SignalValue<readonly [string, string, string]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Required #RRGGBB endpoint and center colors.

[View source — packages/core/src/features/viz/lib/color-types.ts:57](/source/packages/core/src/features/viz/lib/color-types-ts/#L57)

</details>

<span id="api-DivergingColorScaleProps-children"></span>
<details>
<summary>children (optional)</summary>


```ts
readonly children?: PibblNode
```

Related API: [PibblNode](/reference/types/elements-components/#pibblnode).

Descendants consuming the mapping. See PibblNode.

[View source — packages/core/src/features/viz/lib/color-types.ts:60](/source/packages/core/src/features/viz/lib/color-types-ts/#L60)

</details>

<span id="api-ResolvedSequentialColorScale"></span>

### ResolvedSequentialColorScale

Readonly continuous two-stop color mapping.

```ts
interface ResolvedSequentialColorScale
```

Related API: [ResolvedSequentialColorScale](/reference/components/color-scales/).

#### See also

[SequentialColorScaleProps](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/color-types.ts:9](/source/packages/core/src/features/viz/lib/color-types-ts/#L9)

#### Properties and methods

<span id="api-ResolvedSequentialColorScale-domain"></span>
<details>
<summary>domain</summary>


```ts
readonly domain: readonly [number, number]
```

Authored finite endpoints, preserving ascending or descending order.

[View source — packages/core/src/features/viz/lib/color-types.ts:10](/source/packages/core/src/features/viz/lib/color-types-ts/#L10)

</details>

<span id="api-ResolvedSequentialColorScale-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: readonly [string, string]
```

Canonical endpoint colors, in authored order.

[View source — packages/core/src/features/viz/lib/color-types.ts:14](/source/packages/core/src/features/viz/lib/color-types-ts/#L14)

</details>

<span id="api-ResolvedSequentialColorScale-stops"></span>
<details>
<summary>stops</summary>


```ts
readonly stops: readonly ColorScaleStop[]
```

Related API: [ColorScaleStop](/reference/components/color-scales/).

Frozen endpoint/value pairs for scale-derived annotations.

[View source — packages/core/src/features/viz/lib/color-types.ts:18](/source/packages/core/src/features/viz/lib/color-types-ts/#L18)

</details>

<span id="api-ResolvedSequentialColorScale-map"></span>
<details>
<summary>map</summary>


```ts
map: (value: number) => string
```

Maps finite data to a clamped color.

##### Parameters

- **`value`** — Numeric input.

##### Returns

Canonical #rrggbb color.

[View source — packages/core/src/features/viz/lib/color-types.ts:21](/source/packages/core/src/features/viz/lib/color-types-ts/#L21)

</details>

<span id="api-ResolvedDivergingColorScale"></span>

### ResolvedDivergingColorScale

Readonly continuous mapping with an explicit center.

```ts
interface ResolvedDivergingColorScale
```

Related API: [ResolvedDivergingColorScale](/reference/components/color-scales/).

#### See also

[DivergingColorScaleProps](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/color-types.ts:24](/source/packages/core/src/features/viz/lib/color-types-ts/#L24)

#### Properties and methods

<span id="api-ResolvedDivergingColorScale-domain"></span>
<details>
<summary>domain</summary>


```ts
readonly domain: readonly [number, number, number]
```

Strictly monotonic finite endpoints and center, in authored order.

[View source — packages/core/src/features/viz/lib/color-types.ts:25](/source/packages/core/src/features/viz/lib/color-types-ts/#L25)

</details>

<span id="api-ResolvedDivergingColorScale-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: readonly [string, string, string]
```

Canonical endpoint and center colors.

[View source — packages/core/src/features/viz/lib/color-types.ts:30](/source/packages/core/src/features/viz/lib/color-types-ts/#L30)

</details>

<span id="api-ResolvedDivergingColorScale-stops"></span>
<details>
<summary>stops</summary>


```ts
readonly stops: readonly ColorScaleStop[]
```

Related API: [ColorScaleStop](/reference/components/color-scales/).

Frozen endpoint/center pairs for scale-derived annotations.

[View source — packages/core/src/features/viz/lib/color-types.ts:35](/source/packages/core/src/features/viz/lib/color-types-ts/#L35)

</details>

<span id="api-ResolvedDivergingColorScale-map"></span>
<details>
<summary>map</summary>


```ts
map: (value: number) => string
```

Maps finite data through the authored center.

##### Parameters

- **`value`** — Numeric input.

##### Returns

Canonical #rrggbb color.

[View source — packages/core/src/features/viz/lib/color-types.ts:38](/source/packages/core/src/features/viz/lib/color-types-ts/#L38)

</details>

<span id="api-ThresholdColorScale"></span>

### ThresholdColorScale

Provides a lazy, discrete threshold-to-color mapping for descendants.

```ts
ThresholdColorScale: (props: ThresholdColorScaleProps) => PibblNode
```

Related API: [ThresholdColorScale](/reference/components/color-scales/), [ThresholdColorScaleProps](/reference/components/color-scales/), [PibblNode](/reference/types/elements-components/#pibblnode).

#### Parameters

- **`props`** — Boundaries, colors, identity and descendants. See [ThresholdColorScaleProps](/reference/components/color-scales/).

#### Returns

Descendant content.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:90](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L90)

<span id="api-useThresholdColorScale"></span>

### useThresholdColorScale

Reads the matching ancestor threshold color mapping.

```ts
useThresholdColorScale: (id: ScaleId) => Signal<ResolvedThresholdColorScale>
```

Related API: [useThresholdColorScale](/reference/components/color-scales/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedThresholdColorScale](/reference/components/color-scales/).

#### Parameters

- **`id`** — Provider identity. See [ScaleId](/reference/components/scale/).

#### Returns

Shared readonly mapping signal. See [ResolvedThresholdColorScale](/reference/components/color-scales/).

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:101](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L101)

<span id="api-ThresholdColorBand"></span>

### ThresholdColorBand

One lower-inclusive, upper-exclusive threshold color bucket.

```ts
interface ThresholdColorBand
```

Related API: [ThresholdColorBand](/reference/components/color-scales/).

#### See also

[ResolvedThresholdColorScale](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:12](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L12)

#### Properties and methods

<span id="api-ThresholdColorBand-lower"></span>
<details>
<summary>lower</summary>


```ts
readonly lower: number | undefined
```

Lower inclusive boundary, omitted for the first bucket.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:14](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L14)

</details>

<span id="api-ThresholdColorBand-upper"></span>
<details>
<summary>upper</summary>


```ts
readonly upper: number | undefined
```

Upper exclusive boundary, omitted for the last bucket.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:16](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L16)

</details>

<span id="api-ThresholdColorBand-color"></span>
<details>
<summary>color</summary>


```ts
readonly color: string
```

Validated #RRGGBB paint for this bucket.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:18](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L18)

</details>

<span id="api-ThresholdColorScaleProps"></span>

### ThresholdColorScaleProps

Authored threshold boundaries, bucket colors, identity, and descendant content.

```ts
interface ThresholdColorScaleProps
```

Related API: [ThresholdColorScaleProps](/reference/components/color-scales/).

#### See also

[ResolvedThresholdColorScale](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:36](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L36)

#### Properties and methods

<span id="api-ThresholdColorScaleProps-id"></span>
<details>
<summary>id</summary>


```ts
readonly id: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Stable provider identity.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:38](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L38)

</details>

<span id="api-ThresholdColorScaleProps-thresholds"></span>
<details>
<summary>thresholds</summary>


```ts
readonly thresholds: SignalValue<readonly number[]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Strictly ascending finite boundaries; each equality belongs to the upper bucket.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:40](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L40)

</details>

<span id="api-ThresholdColorScaleProps-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: SignalValue<readonly string[]>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Exactly one #RRGGBB color per bucket.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:42](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L42)

</details>

<span id="api-ThresholdColorScaleProps-children"></span>
<details>
<summary>children (optional)</summary>


```ts
readonly children?: PibblNode
```

Related API: [PibblNode](/reference/types/elements-components/#pibblnode).

Descendant content using this dedicated color context.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:44](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L44)

</details>

<span id="api-ResolvedThresholdColorScale"></span>

### ResolvedThresholdColorScale

Immutable resolved threshold mapping shared with descendant marks.

```ts
interface ResolvedThresholdColorScale
```

Related API: [ResolvedThresholdColorScale](/reference/components/color-scales/).

#### See also

[ThresholdColorScaleProps](/reference/components/color-scales/)

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:22](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L22)

#### Properties and methods

<span id="api-ResolvedThresholdColorScale-thresholds"></span>
<details>
<summary>thresholds</summary>


```ts
readonly thresholds: readonly number[]
```

Strictly ascending finite authored bucket boundaries.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:24](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L24)

</details>

<span id="api-ResolvedThresholdColorScale-colors"></span>
<details>
<summary>colors</summary>


```ts
readonly colors: readonly string[]
```

One validated color for every bucket.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:26](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L26)

</details>

<span id="api-ResolvedThresholdColorScale-bands"></span>
<details>
<summary>bands</summary>


```ts
readonly bands: readonly ThresholdColorBand[]
```

Related API: [ThresholdColorBand](/reference/components/color-scales/).

Readable bucket descriptions in authored order.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:28](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L28)

</details>

<span id="api-ResolvedThresholdColorScale-map"></span>
<details>
<summary>map</summary>


```ts
readonly map: (value: number) => string
```

Maps a finite numeric value to its containing bucket paint.

##### Parameters

- **`value`** — Finite input.

##### Returns

Canonical lowercase #rrggbb color.

[View source — packages/core/src/features/viz/lib/threshold-color-scale.ts:32](/source/packages/core/src/features/viz/lib/threshold-color-scale-ts/#L32)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Explicit color scales](/minimal-examples/viz/colors/): Map real observations with dedicated providers and authored palettes. [Plain source](/minimal/viz/colors.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.