colorscope

Color extraction, analysis, and harmony generation for Node.js and the browser.

Install

npm install colorscope

Usage

Extract colors from an image (Node.js only)

import { extractColorsFromBuffer } from "colorscope/extraction";
import { readFile } from "node:fs/promises";

const buffer = await readFile("photo.jpg");
const { colors, background } = await extractColorsFromBuffer(buffer);

Analyze a palette (browser-safe)

import { analyzePalette } from "colorscope/analysis";

const analysis = analyzePalette(colors);
// { temperature, vibrancy, brightness, complexity, dominantFamily, mood }

Generate harmonies (browser-safe)

import { generateHarmony } from "colorscope/harmony";

const complementary = generateHarmony({ h: 200, s: 80, l: 50 }, "complementary");

Sub-path imports

The barrel export (import from "colorscope") pulls in sharp (Node-only native module). Client/browser code must use sub-path imports:

| Import | Purpose | |--------|---------| | colorscope/extraction | Image color extraction (Node-only, requires sharp) | | colorscope/border | Image border detection (Node-only, requires sharp) | | colorscope/analysis | Palette analysis (temperature, vibrancy, mood) | | colorscope/harmony | Harmony generation (complementary, analogous, triadic, etc.) | | colorscope/convert | Color space conversions (OKLab, OKLCH, HSL, RGB, hex) | | colorscope/accessibility | Contrast ratios, color blindness simulation | | colorscope/naming | Human-readable color names, color group search | | colorscope/format | Export palettes as CSS, Tailwind, or SCSS | | colorscope/math | Low-level color math (quantization, distance, conversions) | | colorscope/types | TypeScript types (QuantizedColor, HSL, OKLab, etc.) |

Key features

• Perceptual color science — OKLab/OKLCH color space throughout
• Smart extraction — background detection, JPEG artifact filtering, perceptual merging
• 10 harmony types — complementary, analogous, triadic, split-complementary, tetradic, and more
• Tonal palettes — Material Design-inspired tonal generation
• Accessibility — WCAG contrast ratios and color blindness simulation (protanopia, deuteranopia, tritanopia)
• 374 tests with vitest

License

MIT