@fyipedia/colorfyi

Pure TypeScript color engine for developers. Convert between 7 color spaces (hex, RGB, HSL, HSV, CMYK, CIE Lab, OKLCH), check WCAG contrast ratios, generate color harmonies and Tailwind-style shades, simulate color blindness, and create smooth gradients -- all with zero dependencies.

Extracted from ColorFYI, a color reference platform with 809 named colors across 6 color systems (CSS, X11, Crayola, Pantone, RAL, NCS), 544 brand color palettes, and interactive tools used by developers and designers worldwide.

Try the interactive tools at colorfyi.com -- color converter, contrast checker, palette generator, shade generator, color blindness simulator, and gradient generator.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • Color Space Conversion
  • WCAG Contrast Checking
  • Color Harmonies
  • Tailwind-Style Shades
  • Color Blindness Simulation
  • Perceptual Color Comparison
• API Reference
• TypeScript Types
• Features
• Learn More About Color
• Also Available
• FYIPedia Developer Tools
• License

Install

npm install @fyipedia/colorfyi

Works in Node.js, Deno, Bun, and browsers (ESM).

Quick Start

import { getColorInfo, contrastRatio, harmonies, generateShades } from "@fyipedia/colorfyi";

// Convert any hex color to 7 color spaces instantly
const info = getColorInfo("FF6B35");
console.log(info.rgb);    // { r: 255, g: 107, b: 53 }
console.log(info.hsl);    // { h: 16, s: 100, l: 60.4 }
console.log(info.cmyk);   // { c: 0, m: 58, y: 79.2, k: 0 }
console.log(info.oklch);  // { l: 0.685, c: 0.179, h: 42.9 }

// WCAG 2.1 contrast ratio with AA/AAA compliance checks
const cr = contrastRatio("FF6B35", "FFFFFF");
console.log(cr.ratio);      // 3.38
console.log(cr.aaLarge);    // true
console.log(cr.aaaNormal);  // false

// Generate all 5 harmony types at once
const h = harmonies("FF6B35");
console.log(h.complementary);       // ["35C0FF"]
console.log(h.analogous);           // ["FF3535", "FFA135"]
console.log(h.triadic);             // ["6B35FF", "35FF6B"]

// Tailwind-style shade palette (50-950)
const shades = generateShades("3498DB");
for (const shade of shades) {
  console.log(`${shade.level}: #${shade.hex}`);
}

What You Can Do

Color Space Conversion

Convert between 7 color spaces in a single call. Each space has different strengths:

| Color Space | Best For | Example | |-------------|----------|---------| | Hex | Web/CSS, shorthand notation | #FF6B35 | | RGB | Screen display, digital design | rgb(255, 107, 53) | | HSL | Intuitive hue/saturation/lightness adjustments | hsl(16, 100%, 60%) | | HSV | Color pickers (Photoshop, Figma) | hsv(16, 79%, 100%) | | CMYK | Print design, physical media | cmyk(0%, 58%, 79%, 0%) | | CIE Lab | Perceptually uniform comparisons, Delta E | Lab(65.4, 42.1, 47.8) | | OKLCH | Modern CSS (oklch()), perceptual palettes | oklch(0.685, 0.179, 42.9) |

import { getColorInfo } from "@fyipedia/colorfyi";

const info = getColorInfo("3B82F6");  // Tailwind Blue 500
console.log(info.rgb);    // { r: 59, g: 130, b: 246 }
console.log(info.hsl);    // { h: 217.2, s: 91.2, l: 59.8 }
console.log(info.oklch);  // { l: 0.623, c: 0.184, h: 259.1 }

Learn more: Color Converter Tool · What is OKLCH? · Color Space Guide

WCAG Contrast Checking

Test color pairs against WCAG 2.1 accessibility guidelines. The Web Content Accessibility Guidelines require a minimum contrast ratio of 4.5:1 for normal text (AA) and 7:1 for enhanced contrast (AAA).

import { contrastRatio, textColorForBg } from "@fyipedia/colorfyi";

// Check if your color combination is accessible
const cr = contrastRatio("1E40AF", "FFFFFF");  // Dark blue on white
console.log(cr.ratio);       // 8.55
console.log(cr.aaNormal);   // true  (>= 4.5:1)
console.log(cr.aaLarge);    // true  (>= 3:1)
console.log(cr.aaaNormal);  // true  (>= 7:1)
console.log(cr.aaaLarge);   // true  (>= 4.5:1)

// Automatically pick black or white text for any background
const text = textColorForBg("FF6B35");  // -> "000000" (black text)

Learn more: WCAG Contrast Checker · Contrast Ratio Guide

Color Harmonies

Generate aesthetically pleasing color combinations based on color wheel theory. Five harmony types cover different design needs:

| Harmony | Description | Use Case | |---------|-------------|----------| | Complementary | Opposite on the color wheel | High contrast, bold designs | | Analogous | Adjacent colors (+/-30 degrees) | Cohesive, harmonious palettes | | Triadic | Three evenly spaced (120 degrees) | Vibrant, balanced layouts | | Split-complementary | Complement + neighbors | Softer contrast than complementary | | Tetradic | Four colors (rectangle) | Rich, complex color schemes |

import { harmonies } from "@fyipedia/colorfyi";

const h = harmonies("FF6B35");
console.log(h.complementary);        // ["35C0FF"]
console.log(h.analogous);            // ["FF3535", "FFA135"]
console.log(h.triadic);              // ["6B35FF", "35FF6B"]
console.log(h.splitComplementary);   // ["3565FF", "35FFA1"]
console.log(h.tetradic);             // ["C035FF", "35FF6B", "35C0FF"]

Learn more: Palette Generator · Color Harmony Guide

Tailwind-Style Shades

Generate a full 50-950 shade scale from any base color, matching Tailwind CSS conventions. Essential for building design systems and consistent UI themes.

import { generateShades } from "@fyipedia/colorfyi";

const shades = generateShades("3B82F6");  // Generate shades from Tailwind Blue 500
// shade.level: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
for (const shade of shades) {
  console.log(`${shade.level}: #${shade.hex}`);
}

Learn more: Shade Generator · Tailwind CSS Colors

Color Blindness Simulation

Approximately 8% of men and 0.5% of women have some form of color vision deficiency (CVD). Simulate how your colors appear to users with different types of color blindness using Vienot transformation matrices.

import { simulateColorBlindness } from "@fyipedia/colorfyi";

const cb = simulateColorBlindness("FF6B35");
console.log(cb.protanopia);     // Red-blind (~1% of men)
console.log(cb.deuteranopia);   // Green-blind (~6% of men, most common)
console.log(cb.tritanopia);     // Blue-blind (rare, ~0.01%)
console.log(cb.achromatopsia);  // Total color blindness (monochromacy)

Learn more: Color Blindness Simulator · Color Vision Deficiency Guide

Perceptual Color Comparison

Compare colors using CIE76 Delta E -- a metric designed to match human perception. Unlike simple RGB distance, Delta E accounts for how our eyes actually perceive color differences.

| Delta E | Perception | |---------|-----------| | 0-1 | Not perceptible | | 1-2 | Barely perceptible | | 2-10 | Perceptible at close look | | 10-50 | Clearly different | | 50+ | Very different |

import { compareColors, mixColors, gradientSteps } from "@fyipedia/colorfyi";

// CIE76 Delta E perceptual distance
const cmp = compareColors("FF6B35", "3498DB");
console.log(cmp.deltaE);           // 55.4
console.log(cmp.deltaECategory);   // "Very Different"

// Mix colors in Lab space (perceptually uniform)
const mixed = mixColors("FF0000", "0000FF", 0.5);

// Smooth gradient with perceptual interpolation
const colors = gradientSteps("FF6B35", "3498DB", 7);

Learn more: Gradient Generator · Delta E Explained

API Reference

Color Conversion

| Function | Description | |----------|-------------| | hexToRgb(hex) -> RGB | HEX to RGB | | rgbToHex(r, g, b) -> string | RGB to HEX | | rgbToHsl(r, g, b) -> HSL | RGB to HSL | | hslToRgb(h, s, l) -> RGB | HSL to RGB | | rgbToHsv(r, g, b) -> HSV | RGB to HSV | | rgbToCmyk(r, g, b) -> CMYK | RGB to CMYK | | rgbToLab(r, g, b) -> Lab | RGB to CIE Lab | | labToRgb(l, a, b) -> RGB | CIE Lab to RGB | | rgbToOklch(r, g, b) -> OKLCH | RGB to OKLCH | | getColorInfo(hex) -> ColorInfo | All 7 color spaces at once |

WCAG Contrast

| Function | Description | |----------|-------------| | contrastRatio(hex1, hex2) -> ContrastResult | WCAG 2.1 contrast ratio + AA/AAA checks | | relativeLuminance(r, g, b) -> number | Relative luminance (0-1) | | textColorForBg(hex) -> string | Best text color (black or white) for a background |

Harmonies & Palettes

| Function | Description | |----------|-------------| | harmonies(hex) -> HarmonySet | All 5 harmony types | | complementary(hex) -> string[] | Complementary colors | | analogous(hex) -> string[] | Analogous colors | | triadic(hex) -> string[] | Triadic colors | | splitComplementary(hex) -> string[] | Split-complementary | | tetradic(hex) -> string[] | Tetradic (rectangular) |

Shades

| Function | Description | |----------|-------------| | generateShades(hex) -> ShadeStep[] | Tailwind-style 50-950 |

Comparison & Mixing

| Function | Description | |----------|-------------| | deltaE(hex1, hex2) -> number | CIE76 perceptual distance | | compareColors(hex1, hex2) -> CompareResult | Full comparison report | | mixColors(hex1, hex2, ratio?) -> string | Perceptual mixing in Lab space | | gradientSteps(hex1, hex2, steps?) -> string[] | Smooth gradient | | simulateColorBlindness(hex) -> ColorBlindResult | 4 types of CVD simulation |

TypeScript Types

import type {
  RGB, HSL, HSV, CMYK, Lab, OKLCH,
  ColorInfo, ContrastResult, HarmonySet,
  ShadeStep, ColorBlindResult, CompareResult,
} from "@fyipedia/colorfyi";

Features

• 7 color spaces: RGB, HSL, HSV, CMYK, CIE Lab, OKLCH, Hex
• WCAG 2.1 contrast: AA/AAA compliance checks for normal and large text
• Color harmonies: complementary, analogous, triadic, split-complementary, tetradic
• Shade generation: Tailwind-style 50-950 scale
• Color blindness simulation: protanopia, deuteranopia, tritanopia, achromatopsia (Vienot matrices)
• Perceptual comparison: CIE76 Delta E, Lab-space gradients and mixing
• Zero dependencies: Pure TypeScript, no runtime deps
• Type-safe: Full TypeScript with strict mode
• Tree-shakeable: ESM with named exports
• Fast: All computations under 1ms

Learn More About Color

• Tools: Color Converter · Contrast Checker · Palette Generator · Shade Generator · Blindness Simulator · Gradient Generator
• Color Systems: CSS Named Colors · Pantone Colors · Tailwind Colors · RAL Colors
• Brand Colors: 544 Brand Palettes · Google · Apple · Meta
• Guides: Color Theory Glossary · Blog
• API: REST API Docs · OpenAPI Spec
• Python: PyPI Package · Python Quick Start

Also Available

| Platform | Install | Link | |----------|---------|------| | PyPI | pip install colorfyi | PyPI | | Homebrew | brew tap fyipedia/tap && brew install fyipedia | Tap | | MCP | uvx --from "colorfyi[mcp]" python -m colorfyi.mcp_server | Config | | VSCode | ext install fyipedia.colorfyi-vscode | Marketplace |

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | colorfyi | PyPI | npm | Color conversion, WCAG contrast, harmonies -- colorfyi.com | | emojifyi | PyPI | npm | Emoji encoding & metadata for 3,953 emojis -- emojifyi.com | | symbolfyi | PyPI | npm | Symbol encoding in 11 formats -- symbolfyi.com | | unicodefyi | PyPI | npm | Unicode lookup with 17 encodings -- unicodefyi.com | | fontfyi | PyPI | npm | Google Fonts metadata & CSS -- fontfyi.com | | distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com | | timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com | | namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com | | unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com | | holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com | | cocktailfyi | PyPI | -- | Cocktail ABV, calories, flavor -- cocktailfyi.com | | fyipedia | PyPI | -- | Unified CLI: fyi color info FF6B35 -- fyipedia.com | | fyipedia-mcp | PyPI | -- | Unified MCP hub for AI assistants -- fyipedia.com |

License

MIT