Package Exports
- @instruments/colorscope
- @instruments/colorscope/accessibility
- @instruments/colorscope/analysis
- @instruments/colorscope/border
- @instruments/colorscope/convert
- @instruments/colorscope/embedding
- @instruments/colorscope/extraction
- @instruments/colorscope/format
- @instruments/colorscope/harmony
- @instruments/colorscope/isolation
- @instruments/colorscope/isolation/browser
- @instruments/colorscope/math
- @instruments/colorscope/mood
- @instruments/colorscope/naming
- @instruments/colorscope/naming/semantic
- @instruments/colorscope/naming/server
- @instruments/colorscope/palette
- @instruments/colorscope/palette-library
- @instruments/colorscope/search
- @instruments/colorscope/sorting
- @instruments/colorscope/temperature
- @instruments/colorscope/tolerance
- @instruments/colorscope/types
Readme
colorscope
Color extraction, analysis, and harmony generation for Node.js and the browser.
Access
@instruments/colorscope is currently distributed as a private package. This README
documents the API for internal consumers and repository work, but installation
requires the appropriate registry token and private registry access.
Usage
Extract colors from an image (Node.js only)
import { extractColorsFromBuffer } from "@instruments/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 "@instruments/colorscope/analysis";
const analysis = analyzePalette(colors);
// { temperature, vibrancy, brightness, complexity, dominantFamily, mood }Generate harmonies (browser-safe)
import { generateHarmony } from "@instruments/colorscope/harmony";
const complementary = generateHarmony({ h: 200, s: 80, l: 50 }, "complementary");Sub-path imports
The barrel export (import from "@instruments/colorscope") pulls in sharp (Node-only native module). Client/browser code must use sub-path imports:
| Import | Purpose |
|---|---|
@instruments/colorscope/extraction |
Image color extraction (Node-only, requires sharp) |
@instruments/colorscope/border |
Image border detection (Node-only, requires sharp) |
@instruments/colorscope/analysis |
Palette analysis (temperature, vibrancy, mood) |
@instruments/colorscope/harmony |
Harmony generation (complementary, analogous, triadic, etc.) |
@instruments/colorscope/convert |
Color space conversions (OKLab, OKLCH, HSL, RGB, hex) |
@instruments/colorscope/accessibility |
Contrast ratios, color blindness simulation |
@instruments/colorscope/naming |
Human-readable color names, color group search |
@instruments/colorscope/format |
Export palettes as CSS, Tailwind, or SCSS |
@instruments/colorscope/math |
Low-level color math (quantization, distance, conversions) |
@instruments/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