oklchtohex 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# oklchtohex
+
+`oklchtohex` helps teams using Tailwind v4 convert `oklch(...)` colors into HEX.
+
+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
+
+## Why this approach
+
+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
+
+## Install
+
+```bash
+npm i -D oklchtohex
+```
+
+## CLI usage
+
+Convert one value:
+
+```bash
+npx oklchtohex --value "oklch(70.4% 0.191 22.216)"
+```
+
+Convert a CSS file and write to a new file:
+
+```bash
+npx oklchtohex ./dist/app.css -o ./dist/app.hex.css
+```
+
+Print transformed CSS to stdout:
+
+```bash
+npx oklchtohex ./dist/app.css --stdout
+```
+
+### Options
+
+- `--gamut fit|clip`  
+  `clip` (default) hard-clamps channels; `fit` reduces chroma to stay in sRGB.
+- `--alpha auto|always|never`  
+  defaults to `auto`.
+- `--upper`  
+  outputs uppercase HEX.
+
+When converting Tailwind CSS, known default variables like `--color-red-500` are replaced with the exact Tailwind HEX palette value first. Unknown variables and raw `oklch(...)` values use functional conversion.
+
+## Tailwind v4 integration (Inspect Element workflow)
+
+```json
+{
+  "scripts": {
+    "build:css": "tailwindcss -i ./src/input.css -o ./dist/tailwind.css",
+    "build:css:hex": "oklchtohex ./dist/tailwind.css -o ./dist/tailwind.css",
+    "build": "npm run build:css && npm run build:css:hex"
+  }
+}
+```
+
+This rewrites Tailwind output in-place, so your existing HTML `<link>` remains unchanged and DevTools "Styles" pane shows HEX declarations.
+
+If you want two files instead, output to `./dist/tailwind.hex.css` and link that file.
+
+Note: some browsers still show `rgb(...)` in the "Computed" pane. The "Styles" pane reflects your source declaration format.
+
+## JS API
+
+```js
+import { oklchToHex, replaceOklchInText } from "oklchtohex";
+
+const hex = oklchToHex("oklch(70.4% 0.191 22.216)");
+const css = replaceOklchInText("color: oklch(70.4% 0.191 22.216);");
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "oklchtohex",
+  "version": "0.1.0",
+  "description": "Convert OKLCH colors to HEX and rewrite CSS at build time.",
+  "type": "module",
+  "main": "./src/converter.js",
+  "exports": {
+    ".": "./src/converter.js"
+  },
+  "bin": {
+    "oklchtohex": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "node ./src/cli.js --help"
+  },
+  "keywords": [
+    "oklch",
+    "hex",
+    "tailwind",
+    "tailwindcss",
+    "color",
+    "converter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { oklchToHex, replaceOklchInText } from "./converter.js";
+
+function printHelp() {
+  const help = `
+oklchtohex
+
+Convert OKLCH values to HEX, or rewrite an entire CSS file.
+
+Usage:
+  oklchtohex --value "oklch(70.4% 0.191 22.216)"
+  oklchtohex ./dist/app.css -o ./dist/app.hex.css
+  oklchtohex ./dist/app.css --stdout
+
+Options:
+  --value <oklch>        Convert a single OKLCH value to HEX
+  -o, --output <file>    Output file path for transformed CSS
+  --stdout               Print transformed CSS to stdout
+  --gamut <fit|clip>     Gamut strategy (default: clip)
+  --alpha <auto|always|never>
+                         Include alpha in HEX (default: auto)
+  --upper                Uppercase HEX output
+  -h, --help             Show this help text
+`;
+  process.stdout.write(help);
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    input: undefined,
+    output: undefined,
+    value: undefined,
+    stdout: false,
+    gamut: "clip",
+    includeAlpha: "auto",
+    uppercase: false,
+    help: false
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === "-h" || arg === "--help") {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === "--value") {
+      parsed.value = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "-o" || arg === "--output") {
+      parsed.output = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--stdout") {
+      parsed.stdout = true;
+      continue;
+    }
+    if (arg === "--gamut") {
+      parsed.gamut = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--alpha") {
+      parsed.includeAlpha = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === "--upper") {
+      parsed.uppercase = true;
+      continue;
+    }
+    if (!arg.startsWith("-") && !parsed.input) {
+      parsed.input = arg;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  return parsed;
+}
+
+function normalizeIncludeAlpha(value) {
+  if (!value || value === "auto") {
+    return "auto";
+  }
+  if (value === "always") {
+    return true;
+  }
+  if (value === "never") {
+    return false;
+  }
+  throw new Error(`Invalid --alpha value: ${value}`);
+}
+
+function normalizeGamut(value) {
+  if (value === "fit" || value === "clip") {
+    return value;
+  }
+  throw new Error(`Invalid --gamut value: ${value}`);
+}
+
+async function run() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const options = {
+    gamut: normalizeGamut(args.gamut),
+    includeAlpha: normalizeIncludeAlpha(args.includeAlpha),
+    uppercase: args.uppercase
+  };
+
+  if (args.value) {
+    const hex = oklchToHex(args.value, options);
+    process.stdout.write(`${hex}\n`);
+    return;
+  }
+
+  if (!args.input) {
+    throw new Error("Missing input. Provide --value or a CSS file path.");
+  }
+
+  const inputPath = path.resolve(process.cwd(), args.input);
+  const css = await fs.readFile(inputPath, "utf8");
+  const transformed = replaceOklchInText(css, options);
+
+  if (args.stdout || !args.output) {
+    process.stdout.write(transformed);
+    if (!transformed.endsWith("\n")) {
+      process.stdout.write("\n");
+    }
+    return;
+  }
+
+  const outputPath = path.resolve(process.cwd(), args.output);
+  await fs.writeFile(outputPath, transformed, "utf8");
+}
+
+run().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+});

package/src/converter.js

@@ -0,0 +1,243 @@
+import { getTailwindDefaultHexForVar } from "./tailwind-default-hex.js";
+const OKLCH_REGEX = /oklch\(([^)]*)\)/gi;
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+function parseNumericToken(token) {
+  const value = Number.parseFloat(token);
+  if (Number.isNaN(value)) {
+    throw new Error(`Invalid numeric token: "${token}"`);
+  }
+  return value;
+}
+
+function parseLightness(token) {
+  const trimmed = token.trim().toLowerCase();
+  if (trimmed.endsWith("%")) {
+    return clamp(parseNumericToken(trimmed.slice(0, -1)) / 100, 0, 1);
+  }
+
+  const value = parseNumericToken(trimmed);
+  if (value > 1 && value <= 100) {
+    return clamp(value / 100, 0, 1);
+  }
+  return clamp(value, 0, 1);
+}
+
+function parseHue(token) {
+  const trimmed = token.trim().toLowerCase();
+  if (trimmed.endsWith("deg")) {
+    return parseNumericToken(trimmed.slice(0, -3));
+  }
+  if (trimmed.endsWith("rad")) {
+    return (parseNumericToken(trimmed.slice(0, -3)) * 180) / Math.PI;
+  }
+  if (trimmed.endsWith("turn")) {
+    return parseNumericToken(trimmed.slice(0, -4)) * 360;
+  }
+  return parseNumericToken(trimmed);
+}
+
+function parseAlpha(token) {
+  if (typeof token !== "string") {
+    return 1;
+  }
+
+  const trimmed = token.trim().toLowerCase();
+  if (trimmed.endsWith("%")) {
+    return clamp(parseNumericToken(trimmed.slice(0, -1)) / 100, 0, 1);
+  }
+  return clamp(parseNumericToken(trimmed), 0, 1);
+}
+
+function normalizeHueDegrees(hue) {
+  const normalized = hue % 360;
+  return normalized < 0 ? normalized + 360 : normalized;
+}
+
+export function parseOklch(input) {
+  if (typeof input !== "string") {
+    throw new Error("parseOklch expects a string like oklch(70% 0.2 30)");
+  }
+
+  const trimmed = input.trim();
+  const lower = trimmed.toLowerCase();
+  if (!lower.startsWith("oklch(") || !lower.endsWith(")")) {
+    throw new Error(`Invalid OKLCH function: "${input}"`);
+  }
+
+  const inner = trimmed.slice(trimmed.indexOf("(") + 1, -1).trim();
+  const slashIndex = inner.indexOf("/");
+  const colorPart = slashIndex === -1 ? inner : inner.slice(0, slashIndex).trim();
+  const alphaPart = slashIndex === -1 ? undefined : inner.slice(slashIndex + 1).trim();
+
+  const parts = colorPart
+    .replace(/,/g, " ")
+    .split(/\s+/)
+    .filter(Boolean);
+
+  if (parts.length < 3) {
+    throw new Error(`Invalid OKLCH channels: "${input}"`);
+  }
+
+  const l = parseLightness(parts[0]);
+  const c = Math.max(0, parseNumericToken(parts[1]));
+  const h = normalizeHueDegrees(parseHue(parts[2]));
+  const alpha = parseAlpha(alphaPart);
+
+  return { l, c, h, alpha };
+}
+
+function oklabToLinearSrgb(l, a, b) {
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b;
+
+  const l3 = l_ * l_ * l_;
+  const m3 = m_ * m_ * m_;
+  const s3 = s_ * s_ * s_;
+
+  return {
+    r: +4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
+    g: -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
+    b: -0.0041960863 * l3 - 0.7034186147 * m3 + 1.707614701 * s3
+  };
+}
+
+function oklchToLinearSrgb(l, c, hDegrees) {
+  const radians = (hDegrees * Math.PI) / 180;
+  const a = c * Math.cos(radians);
+  const b = c * Math.sin(radians);
+  return oklabToLinearSrgb(l, a, b);
+}
+
+function isInSrgbGamut(linearRgb) {
+  return (
+    linearRgb.r >= 0 &&
+    linearRgb.r <= 1 &&
+    linearRgb.g >= 0 &&
+    linearRgb.g <= 1 &&
+    linearRgb.b >= 0 &&
+    linearRgb.b <= 1
+  );
+}
+
+function fitChromaToSrgb(l, c, h) {
+  const initial = oklchToLinearSrgb(l, c, h);
+  if (isInSrgbGamut(initial)) {
+    return c;
+  }
+
+  let low = 0;
+  let high = c;
+  for (let i = 0; i < 24; i += 1) {
+    const mid = (low + high) / 2;
+    const rgb = oklchToLinearSrgb(l, mid, h);
+    if (isInSrgbGamut(rgb)) {
+      low = mid;
+    } else {
+      high = mid;
+    }
+  }
+  return low;
+}
+
+function linearToSrgbChannel(channel) {
+  if (channel <= 0.0031308) {
+    return 12.92 * channel;
+  }
+  return 1.055 * channel ** (1 / 2.4) - 0.055;
+}
+
+function channelToHex(channel) {
+  const clamped = clamp(channel, 0, 1);
+  const byte = Math.round(clamped * 255);
+  return byte.toString(16).padStart(2, "0");
+}
+
+function normalizeInput(input) {
+  if (typeof input === "string") {
+    return parseOklch(input);
+  }
+  if (input && typeof input === "object") {
+    if (
+      typeof input.l === "number" &&
+      typeof input.c === "number" &&
+      typeof input.h === "number"
+    ) {
+      return {
+        l: clamp(input.l, 0, 1),
+        c: Math.max(0, input.c),
+        h: normalizeHueDegrees(input.h),
+        alpha: clamp(input.alpha ?? 1, 0, 1)
+      };
+    }
+  }
+  throw new Error("Input must be an OKLCH string or { l, c, h, alpha } object");
+}
+
+export function oklchToHex(input, options = {}) {
+  const { gamut = "clip", includeAlpha = "auto", uppercase = false } = options;
+  const parsed = normalizeInput(input);
+
+  const c =
+    gamut === "fit"
+      ? fitChromaToSrgb(parsed.l, parsed.c, parsed.h)
+      : parsed.c;
+
+  const linear = oklchToLinearSrgb(parsed.l, c, parsed.h);
+  const r = linearToSrgbChannel(linear.r);
+  const g = linearToSrgbChannel(linear.g);
+  const b = linearToSrgbChannel(linear.b);
+
+  let hex = `#${channelToHex(r)}${channelToHex(g)}${channelToHex(b)}`;
+  const shouldIncludeAlpha =
+    includeAlpha === true || includeAlpha === "always" || (includeAlpha === "auto" && parsed.alpha < 1);
+
+  if (shouldIncludeAlpha) {
+    hex += channelToHex(parsed.alpha);
+  }
+
+  return uppercase ? hex.toUpperCase() : hex;
+}
+
+function replaceTailwindDefaultColorVariables(text) {
+  const declarationRegex =
+    /(--color-[a-z]+-\d{2,3})(\s*:\s*)oklch\(([^)]*)\)/gi;
+
+  return text.replace(
+    declarationRegex,
+    (fullMatch, variableName, separator) => {
+      const mappedHex = getTailwindDefaultHexForVar(variableName.toLowerCase());
+      if (!mappedHex) {
+        return fullMatch;
+      }
+      return `${variableName}${separator}${mappedHex}`;
+    }
+  );
+}
+
+export function replaceOklchInText(text, options = {}) {
+  if (typeof text !== "string") {
+    throw new Error("replaceOklchInText expects a string");
+  }
+  const { onError = "preserve", ...convertOptions } = options;
+  const withMappedTailwindDefaults = replaceTailwindDefaultColorVariables(text);
+
+  return withMappedTailwindDefaults.replace(OKLCH_REGEX, (match) => {
+    try {
+      return oklchToHex(match, convertOptions);
+    } catch (error) {
+      if (onError === "throw") {
+        throw error;
+      }
+      return match;
+    }
+  });
+}
+
+export function convertTailwindCssToHex(css, options = {}) {
+  return replaceOklchInText(css, options);
+}

package/src/tailwind-default-hex.js

@@ -0,0 +1,300 @@
+const TAILWIND_HEX_COLORS = {
+  slate: {
+    50: "#f8fafc",
+    100: "#f1f5f9",
+    200: "#e2e8f0",
+    300: "#cbd5e1",
+    400: "#94a3b8",
+    500: "#64748b",
+    600: "#475569",
+    700: "#334155",
+    800: "#1e293b",
+    900: "#0f172a",
+    950: "#020617"
+  },
+  gray: {
+    50: "#f9fafb",
+    100: "#f3f4f6",
+    200: "#e5e7eb",
+    300: "#d1d5db",
+    400: "#9ca3af",
+    500: "#6b7280",
+    600: "#4b5563",
+    700: "#374151",
+    800: "#1f2937",
+    900: "#111827",
+    950: "#030712"
+  },
+  zinc: {
+    50: "#fafafa",
+    100: "#f4f4f5",
+    200: "#e4e4e7",
+    300: "#d4d4d8",
+    400: "#a1a1aa",
+    500: "#71717a",
+    600: "#52525b",
+    700: "#3f3f46",
+    800: "#27272a",
+    900: "#18181b",
+    950: "#09090b"
+  },
+  neutral: {
+    50: "#fafafa",
+    100: "#f5f5f5",
+    200: "#e5e5e5",
+    300: "#d4d4d4",
+    400: "#a3a3a3",
+    500: "#737373",
+    600: "#525252",
+    700: "#404040",
+    800: "#262626",
+    900: "#171717",
+    950: "#0a0a0a"
+  },
+  stone: {
+    50: "#fafaf9",
+    100: "#f5f5f4",
+    200: "#e7e5e4",
+    300: "#d6d3d1",
+    400: "#a8a29e",
+    500: "#78716c",
+    600: "#57534e",
+    700: "#44403c",
+    800: "#292524",
+    900: "#1c1917",
+    950: "#0c0a09"
+  },
+  red: {
+    50: "#fef2f2",
+    100: "#fee2e2",
+    200: "#fecaca",
+    300: "#fca5a5",
+    400: "#f87171",
+    500: "#ef4444",
+    600: "#dc2626",
+    700: "#b91c1c",
+    800: "#991b1b",
+    900: "#7f1d1d",
+    950: "#450a0a"
+  },
+  orange: {
+    50: "#fff7ed",
+    100: "#ffedd5",
+    200: "#fed7aa",
+    300: "#fdba74",
+    400: "#fb923c",
+    500: "#f97316",
+    600: "#ea580c",
+    700: "#c2410c",
+    800: "#9a3412",
+    900: "#7c2d12",
+    950: "#431407"
+  },
+  amber: {
+    50: "#fffbeb",
+    100: "#fef3c7",
+    200: "#fde68a",
+    300: "#fcd34d",
+    400: "#fbbf24",
+    500: "#f59e0b",
+    600: "#d97706",
+    700: "#b45309",
+    800: "#92400e",
+    900: "#78350f",
+    950: "#451a03"
+  },
+  yellow: {
+    50: "#fefce8",
+    100: "#fef9c3",
+    200: "#fef08a",
+    300: "#fde047",
+    400: "#facc15",
+    500: "#eab308",
+    600: "#ca8a04",
+    700: "#a16207",
+    800: "#854d0e",
+    900: "#713f12",
+    950: "#422006"
+  },
+  lime: {
+    50: "#f7fee7",
+    100: "#ecfccb",
+    200: "#d9f99d",
+    300: "#bef264",
+    400: "#a3e635",
+    500: "#84cc16",
+    600: "#65a30d",
+    700: "#4d7c0f",
+    800: "#3f6212",
+    900: "#365314",
+    950: "#1a2e05"
+  },
+  green: {
+    50: "#f0fdf4",
+    100: "#dcfce7",
+    200: "#bbf7d0",
+    300: "#86efac",
+    400: "#4ade80",
+    500: "#22c55e",
+    600: "#16a34a",
+    700: "#15803d",
+    800: "#166534",
+    900: "#14532d",
+    950: "#052e16"
+  },
+  emerald: {
+    50: "#ecfdf5",
+    100: "#d1fae5",
+    200: "#a7f3d0",
+    300: "#6ee7b7",
+    400: "#34d399",
+    500: "#10b981",
+    600: "#059669",
+    700: "#047857",
+    800: "#065f46",
+    900: "#064e3b",
+    950: "#022c22"
+  },
+  teal: {
+    50: "#f0fdfa",
+    100: "#ccfbf1",
+    200: "#99f6e4",
+    300: "#5eead4",
+    400: "#2dd4bf",
+    500: "#14b8a6",
+    600: "#0d9488",
+    700: "#0f766e",
+    800: "#115e59",
+    900: "#134e4a",
+    950: "#042f2e"
+  },
+  cyan: {
+    50: "#ecfeff",
+    100: "#cffafe",
+    200: "#a5f3fc",
+    300: "#67e8f9",
+    400: "#22d3ee",
+    500: "#06b6d4",
+    600: "#0891b2",
+    700: "#0e7490",
+    800: "#155e75",
+    900: "#164e63",
+    950: "#083344"
+  },
+  sky: {
+    50: "#f0f9ff",
+    100: "#e0f2fe",
+    200: "#bae6fd",
+    300: "#7dd3fc",
+    400: "#38bdf8",
+    500: "#0ea5e9",
+    600: "#0284c7",
+    700: "#0369a1",
+    800: "#075985",
+    900: "#0c4a6e",
+    950: "#082f49"
+  },
+  blue: {
+    50: "#eff6ff",
+    100: "#dbeafe",
+    200: "#bfdbfe",
+    300: "#93c5fd",
+    400: "#60a5fa",
+    500: "#3b82f6",
+    600: "#2563eb",
+    700: "#1d4ed8",
+    800: "#1e40af",
+    900: "#1e3a8a",
+    950: "#172554"
+  },
+  indigo: {
+    50: "#eef2ff",
+    100: "#e0e7ff",
+    200: "#c7d2fe",
+    300: "#a5b4fc",
+    400: "#818cf8",
+    500: "#6366f1",
+    600: "#4f46e5",
+    700: "#4338ca",
+    800: "#3730a3",
+    900: "#312e81",
+    950: "#1e1b4b"
+  },
+  violet: {
+    50: "#f5f3ff",
+    100: "#ede9fe",
+    200: "#ddd6fe",
+    300: "#c4b5fd",
+    400: "#a78bfa",
+    500: "#8b5cf6",
+    600: "#7c3aed",
+    700: "#6d28d9",
+    800: "#5b21b6",
+    900: "#4c1d95",
+    950: "#2e1065"
+  },
+  purple: {
+    50: "#faf5ff",
+    100: "#f3e8ff",
+    200: "#e9d5ff",
+    300: "#d8b4fe",
+    400: "#c084fc",
+    500: "#a855f7",
+    600: "#9333ea",
+    700: "#7e22ce",
+    800: "#6b21a8",
+    900: "#581c87",
+    950: "#3b0764"
+  },
+  fuchsia: {
+    50: "#fdf4ff",
+    100: "#fae8ff",
+    200: "#f5d0fe",
+    300: "#f0abfc",
+    400: "#e879f9",
+    500: "#d946ef",
+    600: "#c026d3",
+    700: "#a21caf",
+    800: "#86198f",
+    900: "#701a75",
+    950: "#4a044e"
+  },
+  pink: {
+    50: "#fdf2f8",
+    100: "#fce7f3",
+    200: "#fbcfe8",
+    300: "#f9a8d4",
+    400: "#f472b6",
+    500: "#ec4899",
+    600: "#db2777",
+    700: "#be185d",
+    800: "#9d174d",
+    900: "#831843",
+    950: "#500724"
+  },
+  rose: {
+    50: "#fff1f2",
+    100: "#ffe4e6",
+    200: "#fecdd3",
+    300: "#fda4af",
+    400: "#fb7185",
+    500: "#f43f5e",
+    600: "#e11d48",
+    700: "#be123c",
+    800: "#9f1239",
+    900: "#881337",
+    950: "#4c0519"
+  }
+};
+
+const TAILWIND_HEX_COLOR_MAP = new Map();
+
+for (const [family, scale] of Object.entries(TAILWIND_HEX_COLORS)) {
+  for (const [step, hex] of Object.entries(scale)) {
+    TAILWIND_HEX_COLOR_MAP.set(`--color-${family}-${step}`, hex);
+  }
+}
+
+export function getTailwindDefaultHexForVar(variableName) {
+  return TAILWIND_HEX_COLOR_MAP.get(variableName) ?? null;
+}