oklchtohex 0.4.0 → 0.4.1

package/README.md

@@ -1,18 +1,21 @@
 # oklchtohex
 
-`oklchtohex` helps teams using Tailwind v4 convert `oklch(...)` colors into HEX.
+[![npm version](https://img.shields.io/npm/v/oklchtohex.svg)](https://www.npmjs.com/package/oklchtohex)
+[![license](https://img.shields.io/npm/l/oklchtohex.svg)](https://www.npmjs.com/package/oklchtohex)
+[![npm downloads](https://img.shields.io/npm/dm/oklchtohex.svg)](https://www.npmjs.com/package/oklchtohex)
 
-This is useful when:
-- clients compare implementation colors against Figma tokens shown in HEX
-- QA wants quick visual checks from DevTools
-- you want an optional HEX-only CSS artifact at build time
+Convert CSS `oklch(...)` colors to HEX.
 
-## Why this approach
+Built for teams using Tailwind v4 who want HEX values in generated CSS for QA, client review, and design-tool matching.
 
-A build-time package is the most practical fix:
-- no Tailwind fork required
-- works for any CSS output (including generated Tailwind files)
-- can run in CI and produce a deterministic `*.hex.css` artifact
+## Features
+
+- Converts `oklch(...)` to HEX (`#RRGGBB` / `#RRGGBBAA`)
+- Works as a Vite plugin (auto-convert in `dev` and `build`)
+- Works as a plain JS utility for custom build scripts
+- Handles Tailwind default color variables with exact palette HEX values
+- Handles Tailwind slash opacity utilities like `border-red-500/30`
+- Handles custom theme colors like `border-aurora/40` when emitted via `var(--color-aurora)`
 
 ## Install
 
@@ -20,26 +23,9 @@ A build-time package is the most practical fix:
 npm i -D oklchtohex
 ```
 
-## JS API
-
-```js
-import { oklchToHex, replaceOklchInText, convertTailwindCssToHex } from "oklchtohex";
-
-const hex = oklchToHex("oklch(70.4% 0.191 22.216)");
-const css = replaceOklchInText("color: oklch(70.4% 0.191 22.216);");
-const convertedTailwindCss = convertTailwindCssToHex(css);
-```
+## Quick Start (Vite Plugin)
 
-### Conversion behavior
-
-- Known Tailwind default variables like `--color-red-500` are replaced with exact Tailwind HEX palette values.
-- Unknown variables and raw `oklch(...)` values use functional conversion.
-- Tailwind opacity utilities like `border-red-500/30` and custom theme colors like `border-aurora/40` are handled when emitted as `color-mix(... var(--color-*) ..., transparent)` and converted to 8-digit HEX when the source variable is resolvable.
-- `gamut` option supports `clip` (default) and `fit`.
-
-## Vite plugin (auto on dev + build)
-
-Use the built-in plugin to auto-convert CSS during `vite dev` and `vite build`.
+Add the plugin to `vite.config.js` or `vite.config.ts`:
 
 ```js
 import { defineConfig } from "vite";
@@ -49,52 +35,132 @@ import { oklchToHexVitePlugin } from "oklchtohex/vite";
 export default defineConfig({
   plugins: [
     react(),
-    oklchToHexVitePlugin({
-      gamut: "clip",
-      convertDev: true,
-      convertBuild: true
-    })
+    oklchToHexVitePlugin()
   ]
 });
 ```
 
-### Plugin options
+Default behavior:
+
+- Converts during `vite dev`
+- Converts during `vite build`
+- Uses `gamut: "clip"`
+
+No changes are required to your existing `dev` or `build` commands.
+
+## Vite Plugin Options
+
+```js
+oklchToHexVitePlugin({
+  gamut: "clip",          // "clip" | "fit"
+  includeAlpha: "auto",   // "auto" | "always" | "never"
+  uppercase: false,       // boolean
+  onError: "preserve",    // "preserve" | "throw"
+  convertDev: true,       // boolean
+  convertBuild: true,     // boolean
+  include: /\\.css$/,      // RegExp | (id) => boolean
+  exclude: /legacy\\.css$/  // RegExp | (id) => boolean
+})
+```
+
+## JS API
+
+```js
+import {
+  oklchToHex,
+  replaceOklchInText,
+  convertTailwindCssToHex
+} from "oklchtohex";
+
+const hex = oklchToHex("oklch(63.7% 0.237 25.331)");
+const css = replaceOklchInText(".btn { color: oklch(63.7% 0.237 25.331); }");
+const converted = convertTailwindCssToHex(css);
+```
+
+### `oklchToHex(input, options?)`
+
+- `input`: OKLCH string or `{ l, c, h, alpha? }`
+- Returns: HEX string
+
+Options:
 
 - `gamut`: `"clip"` (default) or `"fit"`
 - `includeAlpha`: `"auto"` (default), `"always"`, `"never"`
 - `uppercase`: `false` (default)
-- `onError`: `"preserve"` (default) or `"throw"`
-- `include`: `RegExp | (id) => boolean` (default matches CSS-like files)
-- `exclude`: `RegExp | (id) => boolean`
-- `convertDev`: `true` by default
-- `convertBuild`: `true` by default
 
-## Tailwind v4 build integration (package-only)
+### `replaceOklchInText(text, options?)`
+
+- Converts all `oklch(...)` values in a string
+- Returns transformed text
+
+Extra option:
+
+- `onError`: `"preserve"` (default) keeps original token on parse/conversion errors
+
+### `convertTailwindCssToHex(css, options?)`
+
+- Alias for `replaceOklchInText` with Tailwind-oriented behavior
 
-Create a small Node script in your app, for example `scripts/convert-tailwind-to-hex.mjs`:
+## Tailwind-Specific Behavior
+
+- Known default variables like `--color-red-500` are replaced with exact Tailwind HEX values.
+- Unknown/custom variables are converted from `oklch(...)` using the converter.
+- `color-mix(in oklab, var(--color-*) <x>%, transparent)` is converted to HEX with alpha when the source variable resolves to HEX.
+- This supports utilities such as `border-red-500/30` and custom ones like `border-aurora/40`.
+
+## Manual Build Script (Non-Plugin Flow)
+
+If you do not want the Vite plugin, run conversion in a custom build script:
 
 ```js
+// scripts/convert-css-to-hex.mjs
 import fs from "node:fs/promises";
 import { convertTailwindCssToHex } from "oklchtohex";
 
 const inputPath = "./dist/tailwind.css";
-const outputPath = "./dist/tailwind.css"; // in-place rewrite
+const outputPath = "./dist/tailwind.css"; // in-place
 
 const css = await fs.readFile(inputPath, "utf8");
 const converted = convertTailwindCssToHex(css, { gamut: "clip" });
 await fs.writeFile(outputPath, converted, "utf8");
 ```
 
-Then call it in your app `package.json`:
+Then wire it in `package.json`:
 
 ```json
 {
   "scripts": {
     "build:css": "tailwindcss -i ./src/input.css -o ./dist/tailwind.css",
-    "build:css:hex": "node ./scripts/convert-tailwind-to-hex.mjs",
+    "build:css:hex": "node ./scripts/convert-css-to-hex.mjs",
     "build": "npm run build:css && npm run build:css:hex"
   }
 }
 ```
 
-This keeps the package library-only while still giving build-time conversion.
+## Notes
+
+- DevTools `Styles` reflects your source CSS format (HEX after conversion).
+- DevTools `Computed` may still show normalized `rgb(...)` in some browsers.
+- Node.js `>=18` is required.
+
+## FAQ
+
+### Do I need to change my `vite dev` or `vite build` commands?
+
+No. If you use `oklchToHexVitePlugin()` in `vite.config.*`, your existing commands stay the same.
+
+### Why do I still see `rgb(...)` in DevTools sometimes?
+
+Browsers often normalize colors in the `Computed` panel. Check the `Styles` panel or generated CSS file to confirm HEX output.
+
+### Does this support Tailwind custom colors like `border-aurora/40`?
+
+Yes. Custom theme variables are converted first, then opacity utilities emitted via `color-mix(... var(--color-*) ..., transparent)` are resolved to HEX with alpha.
+
+### Can I use this without Vite?
+
+Yes. Use the JS API (`replaceOklchInText` / `convertTailwindCssToHex`) in any Node-based build step.
+
+### What if a color token cannot be parsed?
+
+Default behavior is `onError: "preserve"`, which keeps the original token unchanged. Set `onError: "throw"` to fail fast.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oklchtohex",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Convert OKLCH colors to HEX as a JavaScript package.",
   "type": "module",
   "main": "./src/index.js",