Overview
Colorscope — a color science library plus reusable workflow helpers for search, mood, curated palettes, and tolerance.
Colorscope
A color science library for Node.js and the browser. Extract dominant colors from images, analyze palettes, generate harmonies, check accessibility, name colors, and build product-ready color workflows.
Install
pnpm add colorscopePipeline
A typical colorscope workflow:
import {
extractColorsFromUrl,
withColorNames,
analyzePalette,
computeSearchTarget,
buildCuratedPalette,
toleranceToThreshold,
generateHarmony,
meetsWCAG,
paletteToCSS,
} from "colorscope";
// 1. Extract dominant colors from an image
const { colors, background } = await extractColorsFromUrl("https://example.com/photo.jpg");
// 2. Add human-readable names
const named = withColorNames(colors);
// 3. Analyze the palette
const analysis = analyzePalette(named);
// 4. Build a curated picker palette
const picker = buildCuratedPalette(5);
// 5. Turn selections into a search target
const target = computeSearchTarget({
state: {
mode: "palette",
paletteColors: named.slice(0, 3).map((color) => color.hex),
paletteLogic: "all",
searchName: null,
colorHex: null,
moodPreset: null,
gradientStart: null,
gradientEnd: null,
temperature: 0,
lightness: 0.5,
},
});
const threshold = toleranceToThreshold(0.45);
// 6. Generate harmonies from the dominant color
const harmonies = generateHarmony(named[0], "complementary");
// 7. Check contrast accessibility
const wcag = meetsWCAG(named[0].hex, "#ffffff");
// 8. Export as CSS custom properties
const css = paletteToCSS(named);Modules
| Module | Description |
|---|---|
| Extraction | Extract dominant colors from images (Node-only, requires sharp) |
| Math | Low-level color math — quantization, HSL↔RGB↔OKLab, distance |
| Convert | Color space conversion — OKLab, OKLCH, RGB, HSL, Hex |
| Analysis | Palette temperature, vibrancy, brightness, complexity, mood |
| Clustering | K-means color clustering in OKLab space |
| Comparison | Palette distance, sorting, and image comparison |
| Palette Generation | Distillation, accent extraction, harmony scoring |
| Search | Build OKLab search targets from names, palettes, images, and gradients |
| Curated Palette | Generate a stable picker grid from anchor rows |
| Mood | Convert preset feelings and sliders into browse palettes |
| Sorting | Re-order curated palettes by hue or perceptual lightness |
| Tolerance | Map UI sliders to perceptual match thresholds |
| Harmony | Complementary, analogous, triadic schemes + tonal palettes |
| Accessibility | WCAG contrast and color blindness simulation |
| Format | Export as CSS, Tailwind, or SCSS |
| Naming | Color naming + 140 interior design color groups |
Sub-path Imports
The barrel import (import from "colorscope") pulls in the extraction module which depends on sharp (a Node-only native binary). Client components must use sub-path imports to avoid bundling sharp:
// Server-only (Node.js) — barrel import is fine
import { extractColorsFromUrl, withColorNames } from "colorscope";
// Client-safe — use sub-path imports
import type { QuantizedColor } from "colorscope/types";
import { analyzePalette } from "colorscope/analysis";
import { generateHarmony } from "colorscope/harmony";
import { getColorName } from "colorscope/naming";| Sub-path | Key Exports |
|---|---|
colorscope/types | QuantizedColor, HSL, ExtractionResult |
colorscope/math | quantizeHsl, hslToRgb, rgbToOklab, oklabDistance, HUE_VALUES |
colorscope/convert | hexToRgb, hexToOklch, oklabToHex, oklabToOklch, oklchToOklab |
colorscope/analysis | analyzePalette, clusterColors, paletteDistance, harmonyScore |
colorscope/search | computeSearchTarget, computePaletteTarget, computeImageTarget |
colorscope/palette | buildCuratedPalette, CURATED_PALETTE, ANCHOR_ROWS |
colorscope/mood | MOOD_PRESETS, computeMoodTarget, slidersToOklabRegion |
colorscope/sorting | sortPalette, getOklab, SORT_MODES |
colorscope/tolerance | toleranceToThreshold |
colorscope/harmony | generateHarmony, complementary, analogous, triadic, tetradic |
colorscope/accessibility | contrastRatio, meetsWCAG, simulateColorBlindness, checkColorBlindSafety |
colorscope/format | paletteToCSS, paletteToTailwind, paletteToScss |
colorscope/naming | getColorName, searchColourGroup, suggestColourGroups, COLOUR_GROUPS |