📜 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

Data Sources

Color Psychology

• colorpsychology.org
• Color Poster
• Wikipedia

Named Primary, Secondary and Tertiary Colors

• Named color wheel
• Named color wheel 2

Color Adjectives

• Adjective List
• Human Colors

Descriptions

• color meanings

License

MIT