colorfyi 0.2.3

Pure Python color engine — hex to RGB/HSL/CMYK/OKLCH conversion, WCAG contrast checker, color harmonies, Tailwind shades, and color blindness simulation. Zero dependencies.

colorfyi

Pure Python 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 and sub-millisecond performance.

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
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About Color
• Also Available
• Creative FYI Family
• License

Install

pip install colorfyi                # Core engine (zero deps)
pip install "colorfyi[cli]"         # + Command-line interface (typer, rich)
pip install "colorfyi[mcp]"         # + MCP server for AI assistants
pip install "colorfyi[api]"         # + HTTP client for colorfyi.com API
pip install "colorfyi[all]"         # Everything

Or run instantly without installing:

uvx --from colorfyi colorfyi info FF6B35

Quick Start

from colorfyi import get_color_info, contrast_ratio, harmonies, generate_shades

# Convert any hex color to 7 color spaces instantly
info = get_color_info("FF6B35")
print(info.rgb)    # RGB(r=255, g=107, b=53)
print(info.hsl)    # HSL(h=16.0, s=100.0, l=60.4)
print(info.cmyk)   # CMYK(c=0.0, m=58.0, y=79.2, k=0.0)
print(info.oklch)  # OKLCH(l=0.685, c=0.179, h=42.9)

# WCAG 2.1 contrast ratio with AA/AAA compliance checks
cr = contrast_ratio("FF6B35", "FFFFFF")
print(cr.ratio)      # 3.38
print(cr.aa_large)   # True
print(cr.aaa_normal) # False

# Generate all 5 harmony types at once
h = harmonies("FF6B35")
print(h.complementary)  # ['35C0FF']
print(h.analogous)      # ['FF3535', 'FFA135']
print(h.triadic)        # ['6B35FF', '35FF6B']

# Tailwind-style shade palette (50-950)
shades = generate_shades("3498DB")
for shade in shades:
    print(f"{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)

from colorfyi import get_color_info

info = get_color_info("3B82F6")  # Tailwind Blue 500
print(info.rgb)    # RGB(r=59, g=130, b=246)
print(info.hsl)    # HSL(h=217.2, s=91.2, l=59.8)
print(info.oklch)  # OKLCH(l=0.623, c=0.184, h=259.1)

Learn more: Color Converter Tool · 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).

from colorfyi import contrast_ratio, text_color_for_bg

# Check if your color combination is accessible
cr = contrast_ratio("1E40AF", "FFFFFF")  # Dark blue on white
print(cr.ratio)       # 8.55
print(cr.aa_normal)   # True  (≥ 4.5:1)
print(cr.aa_large)    # True  (≥ 3:1)
print(cr.aaa_normal)  # True  (≥ 7:1)
print(cr.aaa_large)   # True  (≥ 4.5:1)

# Automatically pick black or white text for any background
text = text_color_for_bg("FF6B35")  # → "000000" (black text)
text = text_color_for_bg("1E3A5F")  # → "FFFFFF" (white 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°)	Cohesive, harmonious palettes
Triadic	Three evenly spaced (120°)	Vibrant, balanced layouts
Split-complementary	Complement + neighbors	Softer contrast than complementary
Tetradic	Four colors (rectangle)	Rich, complex color schemes

from colorfyi import harmonies

h = harmonies("FF6B35")
print(h.complementary)        # ['35C0FF']
print(h.analogous)            # ['FF3535', 'FFA135']
print(h.triadic)              # ['6B35FF', '35FF6B']
print(h.split_complementary)  # ['3565FF', '35FFA1']
print(h.tetradic)             # ['C035FF', '35FF6B', '35C0FF']

Learn more: Palette Generator · ### 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.

from colorfyi import generate_shades

shades = generate_shades("3B82F6")  # Generate shades from Tailwind Blue 500
# shade.level: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
for shade in shades:
    print(f"{shade.level}: #{shade.hex}")

Learn more: Shade Generator · ### 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 Viénot transformation matrices.

from colorfyi import simulate_color_blindness

cb = simulate_color_blindness("FF6B35")
print(cb.protanopia)     # Red-blind (~1% of men)
print(cb.deuteranopia)   # Green-blind (~6% of men, most common)
print(cb.tritanopia)     # Blue-blind (rare, ~0.01%)
print(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

from colorfyi import compare_colors, mix_colors, gradient_steps

# CIE76 Delta E perceptual distance
cmp = compare_colors("FF6B35", "3498DB")
print(cmp.delta_e)           # 42.3
print(cmp.delta_e_category)  # "Very Different"

# Mix colors in Lab space (perceptually uniform)
mixed = mix_colors("FF0000", "0000FF", ratio=0.5)

# Smooth gradient with perceptual interpolation
colors = gradient_steps("FF6B35", "3498DB", steps=7)

Learn more: Gradient Generator · Delta E Explained

Command-Line Interface

pip install "colorfyi[cli]"

colorfyi info FF6B35                    # Full color info (7 spaces)
colorfyi contrast 000000 FFFFFF         # WCAG contrast check
colorfyi harmonies FF6B35               # Color harmonies
colorfyi shades 3B82F6                  # Tailwind shade palette
colorfyi blindness FF5733               # Color blindness simulation
colorfyi mix FF0000 0000FF              # Mix two colors
colorfyi compare FF6B35 3498DB          # Compare (Delta E)
colorfyi gradient FF0000 0000FF         # Smooth gradient

MCP Server (Claude, Cursor, Windsurf)

Add color tools to any AI assistant that supports Model Context Protocol.

pip install "colorfyi[mcp]"

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "colorfyi": {
            "command": "uvx",
            "args": ["--from", "colorfyi[mcp]", "python", "-m", "colorfyi.mcp_server"]
        }
    }
}

9 tools available: color_info, contrast_check, color_harmonies, color_shades, simulate_color_blindness, mix_colors, compare_colors, gradient, text_color_for_background

REST API Client

pip install "colorfyi[api]"

from colorfyi.api import ColorFYI

with ColorFYI() as api:
    info = api.color("FF6B35")         # GET /api/color/FF6B35/
    cr = api.contrast("000", "FFF")    # GET /api/contrast/?fg=000&bg=FFF
    shades = api.shades("3B82F6")      # GET /api/shades/3B82F6/
    palette = api.palette("FF6B35")    # GET /api/palette/FF6B35/

Full API documentation with OpenAPI spec at colorfyi.com/api/openapi.json.

API Reference

Color Conversion

Function	Description
hex_to_rgb(hex) -> RGB	HEX to RGB
rgb_to_hex(r, g, b) -> str	RGB to HEX
rgb_to_hsl(r, g, b) -> HSL	RGB to HSL
hsl_to_rgb(h, s, l) -> RGB	HSL to RGB
rgb_to_hsv(r, g, b) -> HSV	RGB to HSV
rgb_to_cmyk(r, g, b) -> CMYK	RGB to CMYK
rgb_to_lab(r, g, b) -> Lab	RGB to CIE Lab
lab_to_rgb(l, a, b) -> RGB	CIE Lab to RGB
rgb_to_oklch(r, g, b) -> OKLCH	RGB to OKLCH
get_color_info(hex) -> ColorInfo	All 7 color spaces at once

WCAG Contrast

Function	Description
contrast_ratio(hex1, hex2) -> ContrastResult	WCAG 2.1 contrast ratio + AA/AAA checks
relative_luminance(r, g, b) -> float	Relative luminance (0–1)
text_color_for_bg(hex) -> str	Best text color (black or white) for a background

Harmonies & Palettes

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

Shades & Scales

Function	Description
generate_shades(hex) -> list[ShadeStep]	Tailwind-style 50–950
lightness_scale(hex, steps) -> list[ShadeStep]	Vary lightness only
saturation_scale(hex, steps) -> list[ShadeStep]	Vary saturation only
hue_shift_scale(hex, steps) -> list[str]	Rotate through hue spectrum
monochromatic(hex, count) -> list[str]	Monochromatic palette

Comparison & Mixing

Function	Description
delta_e(hex1, hex2) -> float	CIE76 perceptual distance
compare_colors(hex1, hex2) -> CompareResult	Full comparison report
mix_colors(hex1, hex2, ratio) -> str	Perceptual mixing in Lab space
gradient_steps(hex1, hex2, steps) -> list[str]	Smooth gradient
simulate_color_blindness(hex) -> ColorBlindResult	4 types of CVD simulation

Learn More About Color

• Tools: Color Converter · Contrast Checker · Palette Generator · Shade Generator · Blindness Simulator · Gradient Generator
• Color Systems: CSS Named Colors · - Brand Colors: 544 Brand Palettes · Google · Apple · Meta
• Guides: Color Theory Glossary · Blog
• API: REST API Docs · OpenAPI Spec

Also Available

Platform	Install	Link
npm	npm install @fyipedia/colorfyi	npm
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

Creative FYI Family

Part of the FYIPedia open-source developer tools ecosystem — design, typography, and character encoding.

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

Embed Widget

Embed ColorFYI widgets on any website with colorfyi-embed:

<script src="https://cdn.jsdelivr.net/npm/colorfyi-embed@1/dist/embed.min.js"></script>
<div data-colorfyi="entity" data-slug="example"></div>

Zero dependencies · Shadow DOM · 4 themes (light/dark/sepia/auto) · Widget docs

License

MIT