Naming

Generate human-readable color names from HSL values and search a curated dictionary of 140 interior-design colour groups.

White12

Warm Neutral16

Cool Neutral12

Brown16

Red10

Pink11

Orange12

Yellow10

Green15

Blue15

Purple11

Black5

import { getColorName, searchColourGroup, COLOR_FAMILIES } from "colorscope/naming";

Functions

getColorName

Generate a human-readable color name from HSL values.

function getColorName(h: number, s: number, l: number): string

Param	Type	Description
`h`	`number`	Hue (0-360)
`s`	`number`	Saturation (0-100)
`l`	`number`	Lightness (0-100)

Returns: A descriptive name like "pale blue", "dark green", "charcoal".

Names are composed from modifiers and hue families:

Saturation modifiers: muted (≤30), bright (≥75)
Lightness modifiers: pale (≥70), deep (≤25), dark (≤35)
Achromatic: Colors with saturation ≤15 return white, light gray, gray, charcoal, or black

getColorName(210, 80, 50); // "bright blue"
getColorName(0, 100, 50);  // "bright red"
getColorName(120, 20, 70); // "muted pale green"
getColorName(0, 5, 85);    // "light gray"

searchColourGroup

Resolve a user query to a single ColourGroup using a three-phase search strategy.

function searchColourGroup(query: string): ColourGroup | null

Param	Type	Description
`query`	`string`	Colour name, synonym, or hex code

Returns: Best-matching ColourGroup, or null.

Search phases:

Exact match — Normalized name, synonym, or hex lookup (O(1))
Hex distance — If query is a hex code, finds nearest group by OKLab distance
Fuzzy match — Fuse.js search across names and synonyms (threshold 0.4)

searchColourGroup("terracotta");  // { name: "Terracotta", hex: "#c2704a", ... }
searchColourGroup("#c2704a");     // { name: "Terracotta", ... }
searchColourGroup("terra cotta"); // { name: "Terracotta", ... } (synonym match)
searchColourGroup("teracota");    // { name: "Terracotta", ... } (fuzzy match)

suggestColourGroups

Suggest colour groups for typeahead/autocomplete UIs.

function suggestColourGroups(query: string, limit?: number): ColourGroup[]

Param	Type	Default	Description
`query`	`string`	—	Partial colour name or hex fragment
`limit`	`number`	`8`	Maximum number of suggestions

Returns: Colour groups sorted by descending relevance.

Uses a stricter Fuse.js index (threshold 0.3, distance 50) to favour prefix-style matches.

suggestColourGroups("ter"); // [Terracotta, Thistle, ...]
suggestColourGroups("bl", 3); // [Black, Blue, Blush]

normalizeColourTerm

Normalize user input for comparison.

function normalizeColourTerm(input: string): string

Lowercases, trims, replaces hyphens with spaces, and collapses whitespace.

normalizeColourTerm("Dusty-Rose"); // "dusty rose"

Constants

COLOR_FAMILIES

All base color family names that getColorName can return.

const COLOR_FAMILIES: readonly [
  "red", "orange", "yellow", "green", "teal", "blue",
  "purple", "pink", "white", "black", "gray", "charcoal", "light gray"
]

COLOUR_GROUPS

Dictionary of 140 curated colour groups. Keyed by canonical name, each entry contains:

const COLOUR_GROUPS: Record<string, ColourGroup>

Types

ColorFamily

type ColorFamily = (typeof COLOR_FAMILIES)[number]
// "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "purple" | "pink" | "white" | "black" | "gray" | "charcoal" | "light gray"

ColourGroup

interface ColourGroup {
  name: string;               // Canonical name (e.g., "Terracotta")
  synonyms: string[];         // Alternative names (e.g., ["terra cotta", "clay"])
  family: ColourFamily;       // Parent family
  hex: string;                // Source hex (e.g., "#c2704a")
  hsl: [number, number, number]; // Derived HSL
  oklab: [number, number, number]; // Derived OKLab [L, a, b]
}

ColourFamily

type ColourFamily =
  | "white" | "warm-neutral" | "cool-neutral" | "brown"
  | "red" | "pink" | "orange" | "yellow"
  | "green" | "blue" | "purple" | "black"