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
- 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
Metadata
Release files for colorfyi 0.2.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| colorfyi-0.2.3.tar.gz | 769.6 kB | Without provenance | Details for colorfyi-0.2.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| colorfyi-0.2.3-py3-none-any.whl | Python 3 | none | any | Details for colorfyi-0.2.3-py3-none-any.whl |
Total release size: 790.4 kB
Release files / colorfyi-0.2.3.tar.gz
| Download URL | colorfyi-0.2.3.tar.gz |
|---|---|
| Size | 769.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4958bba38ca4910375c042225328743e0390debbdb011f703e9a8335c3ec71b8
|
|
BLAKE2b-256 checksum How to use checksums |
d0fb596ba08ae295bada007a8c16ce32d87ae1948f4744ebfcccde56bb6fd85e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / colorfyi-0.2.3-py3-none-any.whl
| Download URL | colorfyi-0.2.3-py3-none-any.whl |
|---|---|
| Size | 20.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
91511021cae253862cf2317ea506261162407a8e51639d249e3ad2af138ca2cf
|
|
BLAKE2b-256 checksum How to use checksums |
5fbc9e23a9879a4b0696f59a12126411067f138b627a8d477acf22e9ed81e298
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for colorfyi 0.2.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.