Disclaimer:

This project was created using AI for personal use. Check the Source Code before using it.

oklchme 🎨

A powerful CLI tool to automatically convert RGB, RGBA, and HSL colors to the modern OKLCH color space in your codebase.

Why OKLCH?

OKLCH is a perceptually uniform color space that provides:

• Better color interpolation - Gradients look more natural
• Predictable lightness - Consistent perceived brightness across hues
• Wide gamut support - Access to all colors modern displays can show
• Human-friendly - Intuitive controls for lightness, chroma, and hue

Installation

Run directly with npx (no installation needed):

npx oklchme

Or install globally:

npm install -g oklchme

Usage

Basic Usage

Convert all colors in your CSS files:

npx oklchme

This will scan and convert colors in all CSS, SCSS, JS, JSX, TS, TSX, HTML, and SVG files.

Options

npx oklchme [options]

| Option | Description | Default | | ------------------------- | -------------------------------------------------------- | --------------------------------------------------- | | -p, --pattern <pattern> | Glob pattern for files to process | **/*.{css,scss,sass,less,js,jsx,ts,tsx,html,svg} | | -d, --dry-run | Preview changes without modifying files | false | | --precision <number> | Decimal precision for OKLCH values | 2 | | --ignore <patterns...> | Patterns to ignore | node_modules/**, dist/**, build/**, .git/** | | --preserve-alpha | Preserve alpha channel in output | true | | --format <format> | Output format: oklch, oklch-percent, oklch-decimal | oklch | | -v, --verbose | Show detailed conversion output | false |

Examples

Dry run to preview changes

npx oklchme --dry-run

Convert only CSS files

npx oklchme --pattern "**/*.css"

Convert with higher precision

npx oklchme --precision 4

Verbose output to see all conversions

npx oklchme --verbose

Convert specific directory

npx oklchme --pattern "src/styles/**/*.css"

Supported Color Formats

The tool automatically detects and converts:

RGB Colors

• Hex: #fff, #ffffff, #ffffff80 (with alpha)
• Function: rgb(255, 0, 0), rgb(100% 0% 0%)
• Modern syntax: rgb(255 0 0), rgb(255 0 0 / 0.5)

HSL Colors

• Function: hsl(180, 100%, 50%), hsl(180deg, 100%, 50%)
• With alpha: hsla(180, 100%, 50%, 0.5)
• Modern syntax: hsl(180 100% 50%), hsl(180 100% 50% / 0.5)

Output Formats

Default (oklch)

/* Before */
color: #ff0000;
color: rgb(0, 128, 255);
color: hsl(120, 100%, 50%);

/* After */
color: oklch(62.8% 0.26 29.23);
color: oklch(60.17% 0.15 231.36);
color: oklch(86.65% 0.29 142.5);

Percentage Format (oklch-percent)

Lightness as percentage (0-100%):

color: oklch(62.8% 0.26 29.23);

Decimal Format (oklch-decimal)

Lightness as decimal (0-1):

color: oklch(0.628 0.26 29.23);

Development

Building from source

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in development mode
pnpm dev

Testing

# Run tests
pnpm test

How It Works

1. Scanning: The tool scans your project files based on the provided glob pattern
2. Detection: Uses regex patterns to find RGB, RGBA, and HSL color values
3. Conversion: Converts colors to OKLCH using the culori library for accurate color math
4. Replacement: Replaces original colors with OKLCH equivalents
5. Preservation: Maintains formatting, comments, and alpha channels

Features

• ✅ Fast - Processes multiple files in parallel
• ✅ Safe - Dry-run mode to preview changes
• ✅ Accurate - Uses industry-standard color conversion algorithms
• ✅ Flexible - Configurable patterns and output formats
• ✅ Modern - Supports latest CSS color syntax
• ✅ Preserves Alpha - Maintains transparency values
• ✅ Smart - Skips already-converted OKLCH colors

Browser Support

OKLCH is supported in:

• Chrome 111+
• Firefox 113+
• Safari 15.4+
• Edge 111+

For older browsers, consider using PostCSS with a fallback plugin.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with culori for color conversions
• Inspired by the need for better color spaces in modern web development