postcss-color-golf

⛳️ postcss-color-golf: The only CSS color minifier with a killer short game. Make every color a hole-in-one for your bundle size! 🏌️‍♂️

🏌️ Why use postcss-color-golf?

A hole-in-one for your color values: Shrinks every color down to the shortest, valid CSS output—no mulligans, no gimmicks.
Spec-compliant to the last putt: Always produces legal CSS color codes—no risky “foot wedge” pseudo-shorts.
A caddy for your palette: Swaps in color names, hex, or RGB/RGBA—whichever is shortest for each hole.
Ultra-compatible: Works with PostCSS v8+, ESM, CJS, and TypeScript. Plays nice with your whole plugin bag.
Flexible play: Customizable if you want to tweak your strategy (see options).
Powered by Culori: All color parsing, conversion, and formatting is handled by Culori, supporting all modern and legacy color spaces.

🟢 Features

Hex Shortening:
- Shortens #aabbcc → #abc and #aabbccdd → #abcd only when all pairs match (per CSS spec—no “foot wedge” hacks).
- Never outputs non-standard pseudo-shorts like #abcc for #aabbccc0.
RGB/RGBA Conversion:
- Converts rgb()/rgba() to hex if that’s a better shot.
- Handles alpha like a pro, always going for the legal shortcut.
Color Name Replacement:
- Sinks your color to the shortest form:
  - #f00 → red (a one-stroke win!)
  - fuchsia → #f0f (when it's shorter)
Spec-Compliance Guarantee:
- Always produces valid CSS color codes. If you can putt it on the green, it’ll work in every browser.
Transparency handled:
- Knows when to use transparent—no need for a lost ball search.
No color stuck in the rough:
- Ignores comments and strings, only minifies what’s in play.
Don't handycap yourself:
- You can opt out of minifying colors from spaces that require approximation (like lab, oklab, display-p3, etc.), ensuring your colors never shift unexpectedly.
Culori is your color caddy:
- All color math, parsing, and conversions are handled by Culori. This ensures robust, standards-based support for new and legacy color spaces (lab, lch, oklab, display-p3, rec2020, and more).

📦 Install

npm install postcss-color-golf --save-dev

bun i postcss-color-golf --dev

⚙️ Usage

Note: postcss-color-golf supports ESM (import) and CommonJS (require).

postcss.config.js

module.exports = {
  plugins: [
    require("postcss-color-golf")
    // ...other plugins
  ]
};

ESM (Node ≥ 12+, modern bundlers)

import postcss from "postcss";
import postcssColorGolf from "postcss-color-golf";

postcss([
  postcssColorGolf()
]).process(YOUR_CSS).then(result => {
  console.log(result.css);
});

CommonJS (require)

const postcss = require("postcss");
const postcssColorGolf = require("postcss-color-golf");

postcss([
  postcssColorGolf()
]).process(YOUR_CSS).then(result => {
  console.log(result.css);
});

TypeScript

import postcss from "postcss";
import postcssColorGolf from "postcss-color-golf";

postcss([postcssColorGolf()]).process(cssString).then(result => {
  console.log(result.css);
});

🛠️ API

postcssColorGolf([options])

Options:

Option	Type	Default	Description
preferHex	boolean	true	Prefer hex over named color when output is the same length.
ignoreApproximatedSpaces	boolean	false	If true, skips minifying colors from spaces that may be approximated (lab, oklab, etc).
ignoredSpaces	string[]	[]	List of color space names to skip minifying (e.g. `["lab", "oklab"]`).

🎯 How does the minification tree work?

postcss-color-golf takes every color value and putts it through a rigorous “golf course” of minification, always seeking the shortest legal shot:

Color name or hex? If a CSS color name is the shortest (or a tie and you prefer it), that’s your club.
Can it be short hex? If all pairs are doubled, use 3-digit or 4-digit (#rgb, #rgba). If not, play it safe with 6- or 8-digit.
RGB/RGBA? Converts to hex if that's fewer strokes (characters).
Transparency? Uses 8-digit hex (#rrggbbaa) or transparent if that's the best play.
Never goes out-of-bounds: Won’t use non-standard pseudo-shorts—every output is a legal move per the CSS spec.
Culori is our caddy: All parsing, conversion, and color space support is handled by Culori, meaning you will always get the latest and greatest in color science... in the least number of stokes!

🎨 Example

Input:

a {
  --ts-color-black:#000000;
  color: rgb(255,0,0);
  background: aliceblue;
  border: 1px solid #aabbcc;
  box-shadow:0 0 3px rgba(0,255,0,0.5);
  &::hover {border-color:fuchsia}
}

Output:

a {
  --ts-color-black:#000;
  color: red;
  background: #f0f8ff;
  border: 1px solid #abc;
  box-shadow:0 0 3px #0f080;
  &::hover {border-color:#f0f}
}

📓 Documentation

We maintain detailed documentation in the /docs directory.

🚧 Limitations

Won’t optimize colors in comments or string values—your gallery is safe.
Only works with standard CSS color formats (hex, rgb/a, named colors).
Doesn’t attempt wild color equivalency (no trick shots with HSL, LCH, or device-dependent spaces).
Always spec-compliant; never fudges a rule.

⛳️ FAQ

Why doesn’t it pseudo-shorten, like `#aabbccc0` → `#abcc`?

Because that’s a penalty stroke! The CSS spec only allows #rgba if every pair matches. This plugin guarantees a legal play—your CSS will always render correctly.

Will this break my CSS?

Nope! Every output is a fairway-fresh, standards-compliant CSS color value.

Does it convert color names to hex and vice versa?

Absolutely! If a name is shorter, it’s in the hole. If hex is shorter, it’s getting teed up. You can tweak your preference with the preferHex option for tie-breakers.

Why Culori?

Culori is a modern, actively maintained color library that supports a huge range of color spaces and conversions, with a focus on correctness and standards compliance. By building on Culori, postcss-color-golf ensures your CSS color minification is always up-to-date with the latest color science and browser standards.

🤝 Contributing

Pull requests welcome—bring your best clubs!

Add tests for every new feature or bugfix.
Update the README with your new trick shots.

🏗️ Building

npm run build
# or
bun run build

🧪 Testing

npm run test
# or
bun run test

⚖️ License

CC0 1.0 Universal (Public Domain Dedication) Use it for anything, commercial or personal, with or without attribution. (You don’t even have to yell “fore!”)