Color Types

TypeScript type definitions for CSS colors — providing compile-time validation for color values across all modern CSS color formats.

Features

• Type-Safe Colors: Compile-time validation for all CSS color formats
• Zero Runtime: Type definitions only — no JavaScript code, no dependencies
• 148 CSS Named Colors: All standard W3C color names with case variants
• CSS Color Level 4 & 5: Lab, Lch, Oklab, Oklch, color(), color-mix(), light-dark()
• System Colors & Keywords: 19 CSS system colors + transparent, currentColor
• Modern Syntax: none keyword support, angle unit flexibility (deg, rad, turn, grad)
• Modular Imports: Subpath exports for tree-shaking (import only what you need)
• Object & String Formats: Use objects or strings — full flexibility
• IDE Integration: Complete autocompletion support in TypeScript projects

Installation

npm install --save-dev color-types

Setup

TypeScript Configuration

Add to your tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node16",
    "types": ["color-types"]
  }
}

Note: moduleResolution: "node16" is required for subpath exports to work (e.g., color-types/rgb).

This makes all color types globally available without explicit imports.

Supported Color Formats

| Format | Examples | Notes | |:-------|:---------|:------| | Named Colors | 'red', 'Red', 'RED' | 148 CSS colors, all 3 cases | | System Colors | 'Canvas', 'ButtonFace' | 19 CSS system colors | | Hex | '#ff0000' | Standard hexadecimal notation | | RGB/RGBA | 'rgb(255, 0, 0)', 'rgb(255 0 0 / 100%)' | Comma/space syntax, with none support | | HSL/HSLA | 'hsl(0deg 100% 50%)', 'hsl(0, 100%, 50%)' | deg, rad, turn, grad units, with none support | | HWB | 'hwb(0 0% 0%)', 'hwb(0deg 0% 0% / 1)' | Hue-Whiteness-Blackness, with none support | | Lab/Lch | 'lab(50% 20 30)', 'lch(50% 30 180)' | Perceptually uniform (CIE) color spaces | | Oklab/Oklch | 'oklab(0.5 0.1 0.1)', 'oklch(0.5 0.15 180)' | Modern perceptually uniform color spaces | | color() | 'color(display-p3 1 0 0)' | Generic color function with 10 predefined spaces | | color-mix() | 'color-mix(in srgb, red 50%, blue)' | Mix colors across specified spaces | | light-dark() | 'light-dark(#fff, #000)' | Light/dark mode aware colors | | Objects | {r:255, g:0, b:0}, {l:50, a:20, b:30} | Flexible property naming for any format | | Keywords | 'transparent', 'currentColor' | Special color keywords |

Quick Start

Named Colors

const color: ColorName = 'red'       // ✅ supports all 3 cases
const color: ColorName = 'Red'       // ✅ TitleCase
const color: ColorName = 'RED'       // ✅ UPPERCASE

String Formats

// Basic formats
const color: RGB = 'rgb(255, 0, 0)'
const color: RGBA = 'rgba(255, 0, 0, 0.5)'
const color: HEX = '#ff0000'
const color: HSL = 'hsl(0deg 100% 50%)'
const color: HSLA = 'hsla(0deg 100% 50% / 0.5)'
const color: HWB = 'hwb(0 0% 0%)'

// Modern syntax with none
const color: RGB = 'rgb(255 0 none)'
const color: HSL = 'hsl(0 100% 50% / none)'

// Perceptually uniform spaces
const color: Lab = 'lab(50% 20 30)'
const color: Lch = 'lch(50% 30 180)'
const color: Oklab = 'oklab(0.5 0.1 0.1)'
const color: Oklch = 'oklch(0.5 0.15 180)'

// Advanced functions
const color: ColorFunction = 'color(display-p3 1 0 0)'
const color: ColorMix = 'color-mix(in srgb, red 50%, blue)'
const color: LightDark = 'light-dark(#fff, #000)'

Object Formats

const color: RGBObject  = {r: 255, g: 0, b: 0}         // or {red, green, blue}
const color: RGBAObject = {r: 255, g: 0, b: 0, a: 1}   // or {red, green, blue, alpha}
const color: HSLObject  = {h: 0, s: 100, l: 50}         // or {hue, saturation, lightness}
const color: HWBObject  = {h: 0, w: 0, b: 0}            // or {hue, whiteness, blackness}
const color: LabObject  = {l: 50, a: 20, b: 30}         // or {lightness, a, b}
const color: LchObject  = {l: 50, c: 30, h: 180}        // or {lightness, chroma, hue}
const color: OklabObject = {l: 0.5, a: 0.1, b: 0.1}
const color: OklchObject = {l: 0.5, c: 0.15, h: 180}

Subpath Imports (v2.0)

// Import specific color spaces (recommended for tree-shaking)
import type { RGB, RGBA } from 'color-types/rgb'
import type { Lab, Lch } from 'color-types/lab-lch'
import type { Oklab, Oklch } from 'color-types/oklab-oklch'
import type { ColorMix } from 'color-types/color-mix'
import type { SystemColor } from 'color-types/system-colors'

// Or import everything from main entry (backward compatible)
import type { Color, RGB, Lab, SystemColor } from 'color-types'

Universal Color Type

// Accepts any supported color format
const color: Color = 'red'                              // named color
const color: Color = 'Canvas'                           // system color
const color: Color = '#ff0000'                          // hex
const color: Color = 'rgb(255, 0, 0)'                  // RGB string
const color: Color = 'lab(50% 20 30)'                  // Lab string
const color: Color = 'color(display-p3 1 0 0)'         // color() function
const color: Color = {r: 255, g: 0, b: 0}              // RGB object
const color: Color = {l: 50, a: 20, b: 30}             // Lab object
const color: Color = {hue: 0, saturation: 100, lightness: 50}  // HSL object

Type Reference

| Category | Types | |:---------|:------| | Named Colors | ColorName, ColorNameTitleCase, ColorNameLowerCase, ColorNameUpperCase | | Keywords | SystemColor (19), ColorKeyword (transparent, currentColor), ANSIEscapeCodeColor | | Basic Spaces | RGB, RGBA, HSL, HSLA, HWB, HEX | | Perceptual Spaces | Lab, Lch, Oklab, Oklch | | Functions | ColorFunction, PredefinedColorSpace, ColorMix, MixColorSpace, LightDark | | Objects | RGBObject, RGBAObject, HSLObject, HSLAObject, HWBObject, LabObject, LchObject, OklabObject, OklchObject | | Master | Color — union of all 32+ types |

Migration Guide: v1.0 to v2.0

What's New in v2.0

1. Modular Architecture: Types split into 14 specialized modules
2. Subpath Exports: Import specific color spaces (color-types/rgb, color-types/lab-lch, etc.)
3. New Color Spaces: Lab, Lch, Oklab, Oklch with full object support
4. Advanced Functions: color(), color-mix(), light-dark() functions
5. System Colors: 19 CSS system colors (Canvas, ButtonFace, etc.)
6. Modern Syntax: none keyword support and additional angle units (grad)

Breaking Changes

1. Requires TypeScript 4.7+ (was 4.0+)
2. Requires moduleResolution: "node16" in tsconfig.json
3. Single index.d.ts replaced with 14-file structure

How to Upgrade

Step 1: Update TypeScript

Ensure you're using TypeScript 4.7 or later:

npm install --save-dev typescript@latest

Step 2: Update tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "node16",
    "types": ["color-types"]
  }
}

Step 3: Update color-types Package

npm install --save-dev color-types@latest

Step 4: Optionally Use Subpath Imports

Your existing code will continue to work:

// v1.0 style (still works in v2.0)
import type { RGB, Color } from 'color-types'

But you can optimize for tree-shaking with subpath imports:

// v2.0 recommended style
import type { RGB } from 'color-types/rgb'
import type { Lab } from 'color-types/lab-lch'

What Stays the Same

• All existing type names and signatures are preserved
• Named colors (148 CSS colors with 3 case variants)
• RGB, RGBA, HSL, HSLA, HWB types
• Object format types (RGBObject, HSLObject, etc.)
• ANSI terminal color support
• Zero dependencies and zero runtime code

Zod Validation (v2.1+)

Runtime validation schemas via optional Zod peer dependency:

npm install zod

import { colorSchema, hexSchema, rgbStringSchema } from 'color-types/zod';

// Validate any CSS color
colorSchema.parse('rgb(255, 0, 0)');     // OK
colorSchema.parse('#ff0000');            // OK
colorSchema.parse('Canvas');             // OK (system color)
colorSchema.parse('not-a-color');        // throws ZodError

// Format-specific schemas
hexSchema.parse('#aabbcc');              // OK
rgbStringSchema.parse('rgb(300, 0, 0)'); // throws — out of range

// Object validation with range checks
import { rgbObjectSchema } from 'color-types/zod/rgb';
rgbObjectSchema.parse({ r: 255, g: 0, b: 0 });  // OK
rgbObjectSchema.parse({ r: 300, g: 0, b: 0 });  // throws — r > 255

Available schemas: hexSchema, rgbStringSchema, hslStringSchema, hwbStringSchema, labStringSchema, lchStringSchema, oklabStringSchema, oklchStringSchema, colorFunctionSchema, colorMixSchema, lightDarkSchema, colorNameSchema, systemColorSchema, colorKeywordSchema, plus object schemas for each format.

Documentation

• Project Overview & PDR
• Codebase Summary
• Code Standards
• System Architecture

License

MIT © 2022 DungGramer — Contributions welcome.