🎨 chroma-flow

Accessible color systems, from a single seed.

A zero-dependency TypeScript library & CLI that generates perceptually-uniform, WCAG-compliant, color-blind-safe color palettes using the modern OKLCH color space.

---

🌱 Mission

Make accessible design free and effortless for everyone.

Color accessibility shouldn't be a premium feature locked behind paid design tools. 1 in 12 men and 1 in 200 women live with some form of color vision deficiency, yet most generated palettes are never checked against it. chroma-flow ships WCAG 2.1 contrast checking and color-blind simulation in a tiny, dependency-free package so that every developer can build inclusive interfaces — no SaaS, no signup, no tracking.

This is a non-commercial, community-driven project. It will never be paywalled, ad-supported, or acquired.

✨ Features

• 🧪 OKLCH-based generation — perceptually uniform ramps that look balanced to the human eye.
• ♿ WCAG 2.1 contrast checking — AA / AAA conformance for normal and large text.
• 📏 APCA contrast (WCAG 3 candidate) — signed perceptual Lc values, more accurate than WCAG 2.1 for dark themes.
• 🌗 Light + dark theme generation — a coordinated semantic theme pair (background, surface, text, primary, accent, success/warning/danger) from one seed, with a per-role WCAG + APCA audit.
• 👁️ Color-blind simulation — protanopia, deuteranopia, tritanopia, achromatopsia.
• 🎯 Smart text-color suggestion — auto-pick black or white text for any background.
• 📤 Eight export formats — CSS variables, Tailwind config, JSON, SCSS, SVG swatch sheets, Android colors.xml, SwiftUI Color, Jetpack Compose Color.
• 🖥️ CLI + library — use it in code or from the terminal.
• 🪶 Zero runtime dependencies — auditable in an afternoon, ships tiny.
• 🌲 Tree-shakeable ESM — import only what you use.

📦 Installation

npm install chroma-flow
# or
bun add chroma-flow
# or
pnpm add chroma-flow

Use the CLI globally:

npm install -g chroma-flow
chroma-flow "#6366f1" --format css

…or run it once with bunx / npx:

bunx chroma-flow "#6366f1"

🚀 Quick start

Library

import {
  generatePalette,
  checkContrast,
  suggestTextColor,
  simulateAll,
  exportPalette,
} from "chroma-flow";

// 1. Generate a full 50–950 palette from one seed.
const palette = generatePalette("#6366f1");
console.log(palette[500]); // "#6265f0"

// 2. Export it to CSS variables.
const css = exportPalette(palette, "css", "primary");

// 3. Pick the most readable text color for a background.
const text = suggestTextColor(palette[600]); // "#ffffff"

// 4. Check WCAG conformance.
const result = checkContrast(text, palette[600]);
console.log(result.ratio);           // 8.48
console.log(result.passesAAANormal); // true

// 5. Preview the seed under color vision deficiencies.
simulateAll(palette[500]).forEach((p) =>
  console.log(p.type, p.hex)
);

// 6. (v0.2) Check APCA perceptual contrast (WCAG 3 candidate).
import { checkAPCA } from "chroma-flow";
const apca = checkAPCA("#ffffff", palette[600]);
console.log(apca.Lc);               // -87.6  (negative = light text on dark)
console.log(apca.passesBodyText);   // true   (|Lc| ≥ 75)

// 7. (v0.2) Generate a coordinated light + dark theme.
import { generateTheme, themeToCSS } from "chroma-flow";
const theme = generateTheme("#6366f1");
console.log(theme.light.primary);   // "#3f37bb"
console.log(theme.dark.primary);    // "#8b95ff"
const themeCss = themeToCSS(theme, "brand"); // :root {…} .dark {…}

CLI

# Generate a palette
chroma-flow "#6366f1"

#  50  #e8f5ff  █
# 100  #deecff  ██
# 200  #cad9ff  ████
# ...

# Export as CSS variables
chroma-flow "#6366f1" --format css --name primary

# Export as SwiftUI / Jetpack Compose (v0.2)
chroma-flow "#6366f1" --format swift --name brand
chroma-flow "#6366f1" --format compose --name Brand

# Check WCAG 2.1 contrast against a foreground color
chroma-flow "#f59e0b" --contrast "#000000"

# Check APCA perceptual contrast (v0.2)
chroma-flow "#10b981" --apca "#ffffff"

# Generate a coordinated light + dark theme pair (v0.2)
chroma-flow "#6366f1" --theme --name brand

# Simulate color vision deficiencies
chroma-flow "#6366f1" --cvd

# Tweak the ramp
chroma-flow "#6366f1" --distribution linear --hue-shift -20 --chroma-falloff 0.7

🧠 How it works

chroma-flow converts your seed color into the OKLCH color space (a cylindrical form of OKLab), then walks a lightness ramp across 11 stops while modulating chroma with a falloff curve and an optional hue shift. The result is a smooth, natural-feeling scale where every stop stays inside the sRGB gamut.

OKLCH is chosen over HSL because HSL lightness is not perceptually uniform — a "50% lightness" yellow is far brighter to the eye than a "50% lightness" blue. OKLCH fixes this, so ramps actually look balanced.

seed hex
   │
   ▼
┌──────────┐    ┌──────────────┐    ┌──────────────┐
│ sRGB →   │ ─► │ lightness    │ ─► │ chroma       │
│ OKLCH    │    │ ramp (11)    │    │ falloff      │
└──────────┘    └──────────────┘    └──────┬───────┘
                                            │
                            ┌───────────────┴───────────────┐
                            ▼                               ▼
                    WCAG contrast checks          CVD simulation
                    (AA / AAA)                    (4 conditions)
                            │                               │
                            └───────────────┬───────────────┘
                                            ▼
                            CSS / Tailwind / JSON / SCSS / SVG / XML

📚 API

generatePalette(seed, options?)

Returns a Record<50|100|…|950, string> palette.

Option	Type	Default	Description
distribution	"linear" | "perceptual"	"perceptual"	Lightness distribution across the ramp.
chromaFalloff	number (0–1)	0.5	Vividness of mid-tones vs. extremes.
hueShift	number (degrees)	0	Hue drift across the ramp.
maxChroma	number	0.32	Clamp to avoid out-of-gamut colors.

checkContrast(foreground, background)

Returns { ratio, passesAANormal, passesAALarge, passesAAANormal, passesAAALarge }.

simulateAll(hex)

Returns an array of { type, hex, original } for all four CVD types.

suggestTextColor(background)

Returns "#000000" or "#ffffff", whichever has higher contrast.

exportPalette(palette, format, name?)

Exports to "css" | "tailwind" | "json" | "scss" | "svg" | "android-xml".

See the full API reference for the complete list.

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

• 🐛 Found a bug? Open an issue.
• 💡 Have an idea? Suggest a feature.
• 🔧 Want to code? Grab a good first issue and read CONTRIBUTING.md.

Please review our Code of Conduct before participating.

🗺️ Roadmap

• APCA contrast support (WCAG 3 candidate) — shipped in v0.2.0
• Theme generation (light + dark from one seed) — shipped in v0.2.0
• Swift + Jetpack Compose exporters — shipped in v0.2.0
• Live web playground (in-repo, deployed to GitHub Pages)
• ESM + CJS dual build
• Figma plugin
• Delta-E ∆E2000 color difference helper
• Auto-derivation of complementary / triadic / analogous seeds

📄 License

MIT © Cryptoteep. See LICENSE.

💛 Acknowledgements

• Björn Ottosson for the OKLab / OKLCH color space.
• Machado et al. (2009) for the color vision deficiency simulation matrices.
• The W3C for the WCAG 2.1 contrast specification.

⭐ If chroma-flow helps you build something more accessible, please star the repo — it helps others find it.