@ateliercartographie/ok-palette

Color palette generator for sequential, diverging, and categorical schemes for data visualization and cartography. Also generates pattern palettes compatible with @ateliercartographie/motif.js.

Zero dependencies. Relies entirely on modern browser CSS capabilities (oklch, color-mix()) to guarantee perceptually uniform results.

Created by: Thomas Ansart — Atelier de cartographie de Sciences Po
License: ISC

Installation

pnpm add @ateliercartographie/ok-palette

Quick start

import {
  sequential,
  divergent,
  divergentSequential,
  categorical,
  categoricalPatterns,
  sequentialPatterns,
  resolveColor,
  resolvePalette,
  presets,
  temperature,
} from "@ateliercartographie/ok-palette";

// 5-class monochrome sequential palette
const mono = sequential({ colorStart: "steelblue" });

// 7-class two-tone sequential palette, high contrast
const biTone = sequential({
  colorStart: "#f4e285",
  colorEnd: "#1d3557",
  steps: 7,
  contrast: "high",
});

// Symmetric diverging palette (3+3 classes)
const div = divergent({ colorA: "#3b4cc0" });

// Asymmetric diverging palette, oklch interpolation
const divLch = divergent({
  colorA: "#d7191c",
  colorB: "#2b83ba",
  steps: [5, 2],
  contrast: "high",
  colorSpace: "oklch",
});

// Diverging palette built as two mirrored sequential palettes
const divSeq = divergentSequential({ colorA: "steelblue" });

// 8-color vivid categorical palette
const colors = categorical(8, presets.vif);

// Warm categorical palette with hue offset
const warm = categorical(6, {
  ...presets.vif,
  ...temperature.chaude,
  hueOffset: 30,
});

// Categorical patterns for motif.js
const patterns = categoricalPatterns(6);

// Sequential patterns (size progressively increases with contrast)
const seqPatterns = sequentialPatterns(5, { shape: "line", contrast: "high" });

// Resolve CSS colors to usable values
const css = resolvePalette(mono); // string[]
const webgl = resolvePalette(mono, { format: "webgl" }); // [r,g,b,a][]

API

`sequential(options)`

Generates a sequential palette (monochrome or two-tone).

Option	Type	Default	Description
`colorStart`	`string`	—	CSS start color (light tones)
`colorEnd`	`string?`	`colorStart`	CSS end color (dark tones). If omitted → monochrome
`steps`	`number`	`5`	Number of classes (2–12)
`contrast`	`"low" \| "normal" \| "high"`	`"normal"`	Contrast profile

Returns string[] — CSS colors color-mix(in oklch, …).

How it works

The start color is normalized to a light tone (chroma halved to avoid a fluorescent effect), the end color to a dark tone. The lightness range is automatically adapted to the number of classes via the contrast profile, inspired by ColorBrewer palette analysis:

3 classes → ~30% lightness gap
9 classes → ~70% lightness gap

Interpolation is entirely delegated to the browser via color-mix(in oklch, …): no color library needed.

`divergent(options)`

Generates a diverging (bipolar) palette around a tinted pivot.

Option	Type	Default	Description
`colorA`	`string`	—	Left-extreme CSS color
`colorB`	`string?`	complement of `colorA`	Right-extreme CSS color
`steps`	`[number, number]`	`[3, 3]`	Classes per side `[left, right]`
`contrast`	`"low" \| "normal" \| "high"`	`"normal"`	Contrast profile
`hasCenterClass`	`boolean`	`false`	Add a neutral center class
`colorSpace`	`"oklab" \| "oklch"`	`"oklab"`	Ramp interpolation color space

Returns string[] — CSS colors.

How it works

Both extremes converge toward an automatically derived tinted pivot: the OkLab midpoint of light, highly-desaturated variants of A and B. Because A and B are opposite on the hue wheel, their components almost cancel in OkLab, producing a quasi-neutral, slightly-tinted tone — visually integrated rather than a foreign grey.

colorSpace: "oklab" (default): Cartesian path — smoother, avoids hue artifacts
colorSpace: "oklch": circular path on the hue wheel — more saturated at the center

// Default symmetric palette (7 classes: 3 + 3)
divergent({ colorA: "#3b4cc0" });

// Asymmetric, high contrast, oklch interpolation
divergent({
  colorA: "#d7191c",
  colorB: "#2b83ba",
  steps: [5, 2],
  contrast: "high",
  colorSpace: "oklch",
});

// With a center class (3 + 1 + 3 classes)
divergent({ colorA: "steelblue", steps: [3, 3], hasCenterClass: true });

`divergentSequential(options)`

Generates a diverging palette built as two mirrored sequential() calls — guarantees full consistency with the sequential palette.

Accepts the same options as divergent() except colorSpace (interpolation is always oklch, as in sequential).

Option	Type	Default	Description
`colorA`	`string`	—	Left-extreme color
`colorB`	`string?`	complement	Right-extreme color
`steps`	`[number, number]`	`[3, 3]`	Classes per side
`contrast`	`"low" \| "normal" \| "high"`	`"normal"`	Contrast profile
`hasCenterClass`	`boolean`	`false`	Add a neutral center class

Returns string[] — CSS colors.

// Rigorously identical to two mirrored `sequential` calls
divergentSequential({ colorA: "#3b4cc0" });

// Asymmetric with a center class
divergentSequential({
  colorA: "#d7191c",
  colorB: "#2b83ba",
  steps: [5, 2],
  hasCenterClass: true,
});

`categorical(count, options?)`

Generates a categorical color palette.

Option	Type	Default	Description
`hueRange`	`[number, number]`	`[0, 360]`	Hue range in degrees
`hueOffset`	`number`	`0`	Hue rotation applied to all colors
`chromaRange`	`[number, number]`	`[0.15, 0.25]`	Oklch chroma range
`lightnessRange`	`[number, number]`	`[0.5, 0.75]`	Oklch lightness range, values 0–1

Returns string[] — CSS colors oklch(…).

Presets

presets.vif; // Saturated, vivid colors
presets.pastel; // Soft, light colors
presets.sepia; // Warm, desaturated tones

Temperature filters

temperature.mixte; // Full hue wheel
temperature.chaude; // Reds, oranges, yellows
temperature.froide; // Greens, blues, purples

Combining: categorical(8, { ...presets.vif, ...temperature.chaude })

Van der Corput sequence

Hue distribution relies on the Van der Corput sequence in base 2. It always fills the largest gap on the hue wheel, guaranteeing maximum distance between colors regardless of count.

This approach is non iterative. Performance is independent of class count and very fast (~4ms in modern browsers).

`categoricalPatterns(count, options?)`

Generates categorical pattern parameters compatible with @ateliercartographie/motif.js.

Option	Type	Default	Description
`shapes`	`string[]`	`["line", "circle", "plaid", "triangle"]`	Shapes to cycle through
`angleRange`	`[number, number]`	`[0, 180]`	Angle range (degrees)
`scaleRange`	`[number, number]`	`[2, 8]`	Scale range
`size`	`number`	`10`	Fixed size
`fill`	`string`	`"#000000"`	Fill color
`background`	`string`	`"#ffffff"`	Background color
`patchSize`	`boolean`	`true`	Enable patchSize
`vdcOffset`	`number`	`0`	Van der Corput offset
`colorize`	`boolean \| CategoricalColorOptions`	`false`	Auto-colorize pattern fill via `categorical`

Returns PatternParams[]

How it works

Pattern variation combines three complementary mechanisms so classes stay distinct without looking purely random:

Shape: forms are assigned by cycling through shapes (i % shapes.length) to guarantee balanced reuse when count exceeds the shape list.
Scale: values oscillate between scaleRange[0] and scaleRange[1] (triangle-wave style), creating contrast while avoiding monotonic growth that could suggest an ordered scale.
Angle: orientation is sampled with the Van der Corput sequence, but independently within each shape group. In practice, each shape gets its own low-discrepancy angle stream, which spreads angles evenly and prevents two identical shapes from clustering around similar directions.

`sequentialPatterns(count, options?)`

Generates sequential pattern parameters compatible with @ateliercartographie/motif.js.

Pattern size increases monotonically across classes, analogous to the lightness range in sequential color palettes. The size range is adapted to both the class count and the contrast profile.

The shape is fixed to preserve the perception of order.

Option	Type	Default	Description
`shape`	`string`	`"line"`	Pattern shape
`sizeRange`	`[number, number]`	`[4, 14]`	Size range [small, large]
`angle`	`number`	`45`	Fixed angle (degrees)
`scale`	`number`	`4`	Fixed scale
`contrast`	`"low" \| "normal" \| "high"`	`"normal"`	Contrast profile
`fill`	`string`	`"#000000"`	Fill color
`background`	`string`	`"#ffffff"`	Background color
`patchSize`	`boolean`	`true`	Enable patchSize

Returns PatternParams[]

`resolveColor(color, options?)`

Resolves a complex CSS color (color-mix(…), oklch(from …), etc.) to a usable value.

{ format: "css" } (default) → string as computed by the browser
{ format: "webgl" } → [r, g, b, a] (0–255)

How it works

resolveColor delegates parsing and evaluation to the browser color engine: the input is applied to a temporary element/canvas context, then read back as a computed color.

This ensures full support for modern CSS color syntax (oklch, relative colors, color-mix()) without external dependencies and with behavior aligned to real rendering engines. The function then normalizes the result either as a CSS color string (css) or as a WebGL-ready numeric tuple (webgl).

`resolvePalette(colors, options?)`

Applies resolveColor to an entire array of colors.

Why this approach?

Problem 1 — Color space

The choice of interpolation space dramatically changes the result. Using oklch guarantees perceptually uniform steps across each component (lightness, chroma, hue). As of 2025, oklch is supported by all modern browsers.

Problem 2 — Lightness range

A sequential palette only works if the lightness gap between the first and last color is sufficient and adapted to the number of classes. This library automatically normalizes input colors to guarantee a readable result.

Solution

Universal: normalizes any CSS color before generating the palette
Modern: zero dependencies, relies on native oklch and color-mix()
Performant: the Van der Corput sequence generates categorical palettes in constant time, unlike iterative approaches like I Want Hue

Development

# Start the demo page
pnpm dev

# Build the library
pnpm build

License

ISC — Atelier de cartographie de Sciences Po

Resources

Chroma.js — Documentation
Chroma.js Color Palette Helper
MDN — color-mix()
ColorBrewer
Mastering Multi-hued Color Scales — Gregor Aisch
Van der Corput sequence
@ateliercartographie/motif.js

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
demo		demo
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Navigation Menu

Uh oh!

Repository files navigation

@ateliercartographie/ok-palette

Installation

Quick start

API

`sequential(options)`

How it works

`divergent(options)`

How it works

`divergentSequential(options)`

`categorical(count, options?)`

Presets

Temperature filters

Van der Corput sequence

`categoricalPatterns(count, options?)`

How it works

`sequentialPatterns(count, options?)`

`resolveColor(color, options?)`

How it works

`resolvePalette(colors, options?)`

Why this approach?

Problem 1 — Color space

Problem 2 — Lightness range

Solution

Development

License

Resources

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

@ateliercartographie/ok-palette

Installation

Quick start

API

sequential(options)

How it works

divergent(options)

How it works

divergentSequential(options)

categorical(count, options?)

Presets

Temperature filters

Van der Corput sequence

categoricalPatterns(count, options?)

How it works

sequentialPatterns(count, options?)

resolveColor(color, options?)

How it works

resolvePalette(colors, options?)

Why this approach?

Problem 1 — Color space

Problem 2 — Lightness range

Solution

Development

License

Resources

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`sequential(options)`

`divergent(options)`

`divergentSequential(options)`

`categorical(count, options?)`

`categoricalPatterns(count, options?)`

`sequentialPatterns(count, options?)`

`resolveColor(color, options?)`

`resolvePalette(colors, options?)`