Skip to main content
colorscope

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 colorscope

Pipeline

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

ModuleDescription
ExtractionExtract dominant colors from images (Node-only, requires sharp)
MathLow-level color math — quantization, HSL↔RGB↔OKLab, distance
ConvertColor space conversion — OKLab, OKLCH, RGB, HSL, Hex
AnalysisPalette temperature, vibrancy, brightness, complexity, mood
ClusteringK-means color clustering in OKLab space
ComparisonPalette distance, sorting, and image comparison
Palette GenerationDistillation, accent extraction, harmony scoring
SearchBuild OKLab search targets from names, palettes, images, and gradients
Curated PaletteGenerate a stable picker grid from anchor rows
MoodConvert preset feelings and sliders into browse palettes
SortingRe-order curated palettes by hue or perceptual lightness
ToleranceMap UI sliders to perceptual match thresholds
HarmonyComplementary, analogous, triadic schemes + tonal palettes
AccessibilityWCAG contrast and color blindness simulation
FormatExport as CSS, Tailwind, or SCSS
NamingColor 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-pathKey Exports
colorscope/typesQuantizedColor, HSL, ExtractionResult
colorscope/mathquantizeHsl, hslToRgb, rgbToOklab, oklabDistance, HUE_VALUES
colorscope/converthexToRgb, hexToOklch, oklabToHex, oklabToOklch, oklchToOklab
colorscope/analysisanalyzePalette, clusterColors, paletteDistance, harmonyScore
colorscope/searchcomputeSearchTarget, computePaletteTarget, computeImageTarget
colorscope/palettebuildCuratedPalette, CURATED_PALETTE, ANCHOR_ROWS
colorscope/moodMOOD_PRESETS, computeMoodTarget, slidersToOklabRegion
colorscope/sortingsortPalette, getOklab, SORT_MODES
colorscope/tolerancetoleranceToThreshold
colorscope/harmonygenerateHarmony, complementary, analogous, triadic, tetradic
colorscope/accessibilitycontrastRatio, meetsWCAG, simulateColorBlindness, checkColorBlindSafety
colorscope/formatpaletteToCSS, paletteToTailwind, paletteToScss
colorscope/naminggetColorName, searchColourGroup, suggestColourGroups, COLOUR_GROUPS