📃 Table of Contents

• Features
• Usage
• API
  • Constants
    • SpecialColor
    • SystemColor
    • NamedStandardColor
    • NamedExtendedColor
  • Template literals
    • HexColor
    • RgbColor
    • RgbaColor
    • HslColor
    • HwbColor
    • LabColor
    • LchColor
    • OklabColor
    • OklchColor
    • LightDarkColor
    • ColorMix
    • DeviceCmyk
    • ColorContrast
    • LinearGradient
    • RadialGradient
    • ConicGradient
    • RepeatingLinearGradient
    • RepeatingRadialGradient
    • RepeatingConicGradient
  • Special
    • Color
    • ColorWithKeywords
    • ColorExtended
  • CSS levels
    • CSS level 3
    • CSS level 4
    • CSS level 5
• Examples
• Changelog
• Support
• License
• Related
• Author

🤖 Features

• 🎨 Supports every major CSS color format and keyword
• 🌈 Includes named colors, system colors, and special keywords
• 🔢 Handles HEX, RGB(A), HSL, HWB, Lab, LCH, OKLab, and OKLCH
• 🌀 Covers gradients: linear, radial, conic, and repeating variants
• ⚡ Supports modern CSS functions like color-mix, light-dark, device-cmyk, color-contrast
• 📚 Typed definitions for CSS Color Modules Level 3–6
• 🛡 Strong TypeScript typing for accuracy and autocomplete

🕵🏼 Usage

Install it by executing any of the following, depending on your preferred package manager:

pnpm add @igorskyflyer/common-color

yarn add @igorskyflyer/common-color

npm i @igorskyflyer/common-color

🤹🏼 API

🤖 Constants

SpecialColor

Technically, keywords - not colors per se, they provide ways of using special colors: currentcolor, transparent, initial, inherit and unset.

Each of them has a special meaning for the browser:

• currentcolor: the current color of the element
• transparent: a fully transparent color
• initial: the default value defined by the browser
• inherit: inherits the color from the parent element
• unset: resets the property to its natural value, either inherited or initial

SystemColor

This type represents a set of system-defined color keywords that correspond to system UI elements, which can adapt based on the user's operating system and theme settings.

Includes keywords like: AccentColor, AccentColorText, ActiveText, ButtonBorder, ButtonFace, etc.

[!TIP] Learn more about SystemColor on MDN.

NamedStandardColor

Common and standardized color identifiers. Includes values like: black, silver, gray, white, maroon, red, etc.

NamedExtendedColor

Includes all of the colors defined by NamedStandardColor and 131 colors more, values like: aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, etc.

📜 Template literals

[!CAUTION] The following types are derived from a template literal type, the types do NOT validate the actual color.

HexColor

A template literal type that adheres to the format #${string}, effectively representing a Hex color.

RgbColor

A template literal type that adheres to the format rgb(${string}), effectively representing an RGB color.

RgbaColor

A template literal type that adheres to the format rgba(${string}), effectively representing an RGBA color.

HslColor

A template literal type that adheres to the format hsl(${string}), effectively representing an HSL color.

HwbColor

A template literal type that adheres to the format hwb(${string}), effectively representing an HWB color.

LabColor

A template literal type that adheres to the format lab(${string}), effectively representing a LAB color.

LchColor

A template literal type that adheres to the format lch(${string}), effectively representing a LCH color.

OklabColor

A template literal type that adheres to the format oklab(${string}), effectively representing an Oklab color.

OklchColor

A template literal type that adheres to the format oklch(${string}), effectively representing an Oklch color.

LightDarkColor

A template literal type that adheres to the format light-dark(${string}), effectively representing a light-dark color.

ColorMix

A template literal type that adheres to the format color-mix(${string}), effectively representing a color-mix.

DeviceCmyk

A template literal type that adheres to the format device-cmyk(${string}), effectively representing a device-cmyk color.

ColorContrast

A template literal type that adheres to the format color-contrast(${string}), effectively representing a color-contrast color.

Gradients

[!TIP] Gradients are supported from v1.1.0.

LinearGradient

A template literal type that adheres to the format linear-gradient(${string}), effectively representing a linear gradient.

RadialGradient

A template literal type that adheres to the format radial-gradient(${string}), effectively representing a radial gradient.

ConicGradient

A template literal type that adheres to the format conic-gradient(${string}), effectively representing a conic gradient.

RepeatingLinearGradient

A template literal type that adheres to the format repeating-linear-gradient(${string}), effectively representing a repeating linear gradient.

RepeatingRadialGradient

A template literal type that adheres to the format repeating-radial-gradient(${string}), effectively representing a repeating radial gradient.

RepeatingConicGradient

A template literal type that adheres to the format repeating-conic-gradient(${string}), effectively representing a repeating conic gradient.

🦄 Special

Color

A broad color type that includes all of the previously mentioned color types:

• NamedStandardColor
• NamedExtendedColor
• HexColor
• RgbColor
• RgbaColor
• HslColor
• HwbColor
• LabColor
• LchColor
• OklabColor
• OklchColor
• LightDarkColor
• ColorMix
• DeviceCmyk
• ColorContrast
• LinearGradient
• RadialGradient
• ConicGradient
• RepeatingLinearGradient
• RepeatingRadialGradient
• RepeatingConicGradient

ColorWithKeywords

An even broader color type that includes the Color type (and all of the previously mentioned color types) with the addition of colors from the SpecialColor type.

ColorExtended

The most broad color type that includes the ColorWithKeywords type (and all of the previously mentioned color types) with the addition of colors from the SystemColor type.

CSS levels

In addition to using any color type, since v1.2.0 it is possible to narrow the color types to a certain CSS color module level .

CssLevel3Color

Includes the following CSS color module level 3 types:

• HexColor
• RgbColor
• NamedStandardColor
• RgbaColor
• HslColor
• SystemColor
• NamedExtendedColor
• SpecialColor
• LinearGradient
• RadialGradient
• RepeatingLinearGradient
• RepeatingRadialGradient

CssLevel4Color

Includes previously mentioned CSS color module level 3 types and the following CSS color module level 4 types:

• HwbColor
• LabColor
• LchColor
• OklabColor
• OklchColor
• ConicGradient
• RepeatingConicGradient

CssLevel5Color

Includes previously mentioned CSS color module level 4 types and the following CSS color module level 5 types:

• LightDarkColor
• DeviceCmyk
• ColorMix

CssLevel6Color

Includes previously mentioned CSS color module level 5 types and the following CSS color module level 6 types:

• ColorContrast

🗒️ Examples

ui.ts

import type { Color } from '@igorskyflyer/common-color'

const uiColor: Color = '#0099ff' // ok, now do something with the Hex color
const uiScrollbar: Color = 'rfb(0, 128, 255)' // will trigger an ERROR
                  // (typo, rFb instead of rGb)

📝 Changelog

📑 The changelog is available here, CHANGELOG.md.

🪪 License

Licensed under the MIT license which is available here, MIT license.

💖 Support

🧬 Related

@igorskyflyer/unc-path

🥽 Provides ways of parsing UNC paths and checking whether they are valid. 🎱

@igorskyflyer/keppo

🎡 Parse, manage, compare and output SemVer-compatible version numbers. 🛡

@igorskyflyer/jmap

🕶️ Reads a JSON file into a Map. 🌻

@igorskyflyer/zing

🐌 Zing is a C# style String formatter for JavaScript that empowers Strings with positional arguments - composite formatting. 🚀

@igorskyflyer/duoscribi

✒ DúöScríbî allows you to convert letters with diacritics to regular letters. 🤓

👨🏻‍💻 Author

Created by Igor Dimitrijević (@igorskyflyer).