0.21.0 • Published 1 month ago

color-description

Licence

MIT

Version

0.21.0

Deps

Size

283 kB

Vulns

Weekly

Stars

Summary Dependency Versions

color-description

Color-Description is a class that turns a technical color representation into a human readable description.

Installation

npm install color-description

Usage

import ColorDescription from "color-description/dist/index.esm";

console.log(ColorDescription);

const cd = new ColorDescription("#ffffff");

console.log(cd.getDescriptiveList());
/**
 * pale, light, faded, delicate, glistening, bleached, neutral colorless, bright, briliant and high
 **/

console.log(cd.meanings);
console.log(cd.effects);
console.log(cd.usage);

cd.color = "red";

console.log(cd.getDescriptiveList());
/**
 * saturated, strong, lush, ablaze, beaming, bold, brilliant, flamboyant, vibrant, vivid, loud, very saturated, warm, mellow, red and reddish
 **/

console.log(cd.meanings);
/**
 * ["excitement", "energy", "passion", ...]
 **/

console.log(cd.effects);
/**
 * ["stimulate", "create urgency", "draw attention", ...]
 **/

console.log(cd.usage);
/**
 * ["caution", "food industry", "sports", ...]
 **/

Color Meaning & Translation

The default dataset is written in English, and its meanings, effects, and usage labels are subjective and written from a western perspective: English dataset

Interpretation model used by the dataset:

meanings are symbolic associations
effects are perceptual or behavioral effects
usage is contextual fit such as industries, themes, and applications

API

`ColorDescription`

Constructor

const cd = new ColorDescription(color);

color (string | object): A color representation (hex, rgb, hsl, or similar)

Methods

getDescriptiveList(): Returns an array of descriptive words for the color
getColorFamily(): Returns the color family/category (e.g., "red", "blue")

Properties

color: Get or set the current color
meanings: Symbolic or emotional associations
effects: Typical effects or signals the color can create
usage: Contexts, industries, themes, or applications where the color fits

Module Formats

This package supports multiple module formats:

ESM (modern): dist/index.esm.js
CommonJS (Node.js): dist/index.js
IIFE (browser): dist/index.iife.js

Development

# Build all formats
npm run build

# Run tests
npm run test

# Development with watch mode
npm run dev

Perceptually Accurate Color Matching

All color matching is performed in OKLCH color space, which provides perceptually uniform lightness, chroma, and hue — unlike HSL where identical saturation/lightness values can look dramatically different across hues.

Hue name boundaries are empirically grounded using data from ~49,000 English-language color naming responses collected via the Many Languages, Many Colors project. Boundaries are placed at midpoints between adjacent survey-term centroids in OKLCH hue space, ensuring that each color is labeled with the name most English speakers would use.

Kim, Y., Thayer, K., Gorsky, G. S., & Heer, J. (2019). Color Names Across Languages: Salient Colors and Term Translation in Multilingual Color Naming Models. EuroVis 2019. Project repository