@decocms/blocks-cli 7.21.0 → 7.22.0

package/scripts/migrate/templates/app-css.test.ts

@@ -0,0 +1,150 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createContext } from "../types";
+import { generateAppCss } from "./app-css";
+
+describe("generateAppCss — tailwind.config.ts porting", () => {
+  it("emits custom colors, fonts, and breakpoints ported from tailwind.config.ts", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig = {
+      colors: { perola: "#F5F0E8", "brand-500": "#B10200" },
+      fontFamily: { "bebas-neue": "Bebas Neue, sans-serif" },
+      screens: { "3xl": "1920px" },
+      safelist: ["bg-red-500", "text-brand-500"],
+      safelistPatterns: [],
+      plugins: [],
+      reviewItems: [],
+    };
+
+    const css = generateAppCss(ctx);
+
+    expect(css).toContain("--color-perola: #F5F0E8;");
+    expect(css).toContain("--color-brand-500: #B10200;");
+    expect(css).toContain("--font-bebas-neue: Bebas Neue, sans-serif;");
+    expect(css).toContain("--breakpoint-3xl: 1920px;");
+    expect(css).toContain('@source inline("bg-red-500 text-brand-500");');
+  });
+
+  it("does not duplicate a custom color that collides with a daisyUI semantic key", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig.colors = { primary: "#000000" };
+
+    const css = generateAppCss(ctx);
+    // The daisyUI theme's own --color-primary is emitted once in the plugin
+    // block; the ported tailwind.config.ts value must not add a second,
+    // conflicting @theme declaration.
+    const themeBlockMatch = css.match(/@theme \{[\s\S]*?\n\}/);
+    expect(themeBlockMatch).not.toBeNull();
+    const occurrences = (themeBlockMatch![0].match(/--color-primary:/g) ?? []).length;
+    expect(occurrences).toBe(0);
+  });
+
+  it("flags unconvertible safelist regex patterns as manual review items", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig.safelistPatterns = ["/^grid-cols-/"];
+
+    generateAppCss(ctx);
+
+    expect(
+      ctx.manualReviewItems.some((i) => i.reason.includes("/^grid-cols-/")),
+    ).toBe(true);
+  });
+
+  it("uses a custom tailwind.config.ts gray-* override instead of declaring the v3 default gray scale a second time", () => {
+    const ctx = createContext("/tmp/does-not-exist");
+    ctx.tailwindConfig.colors = { "gray-50": "#111111", "gray-500": "#222222" };
+
+    const css = generateAppCss(ctx);
+    const themeBlockMatch = css.match(/@theme \{[\s\S]*?\n\}/);
+    expect(themeBlockMatch).not.toBeNull();
+    const themeBlock = themeBlockMatch![0];
+
+    // gray-50/500 must be declared exactly once, with the custom value —
+    // not once with the custom value and once more with the hardcoded
+    // default (which would silently win via CSS's last-declaration-wins).
+    expect((themeBlock.match(/--color-gray-50:/g) ?? []).length).toBe(1);
+    expect(themeBlock).toContain("--color-gray-50: #111111;");
+    expect(themeBlock).not.toContain("--color-gray-50: #f9fafb;");
+    expect((themeBlock.match(/--color-gray-500:/g) ?? []).length).toBe(1);
+    expect(themeBlock).toContain("--color-gray-500: #222222;");
+    // Untouched shades still fall back to the v3 default.
+    expect(themeBlock).toContain("--color-gray-950: #030712;");
+  });
+});
+
+describe("generateAppCss — oklch fixer scope (gotcha #43)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "app-css-oklch-scope-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("does not rewrite a hex/oklch(var()) pair declared in the site's own original CSS", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "tailwind.css"),
+      `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --icon-color: #1a1a1a;
+}
+.icon {
+  fill: oklch(var(--icon-color));
+}
+`,
+      "utf-8",
+    );
+
+    const ctx = createContext(tmpDir);
+    const css = generateAppCss(ctx);
+
+    // The site's own declaration must survive untouched — the oklch fixer
+    // must not reach into content it doesn't own.
+    expect(css).toContain("--icon-color: #1a1a1a;");
+    expect(css).not.toMatch(/--icon-color:\s*[\d.]+\s+[\d.]+\s+[\d.]+;/);
+  });
+});
+
+describe("generateAppCss — @apply rewrites classes behind a modifier prefix", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "app-css-apply-variant-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("renames a variant-prefixed class inside @apply, not just bare tokens", () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "tailwind.css"),
+      `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer components {
+  .btn-brand {
+    @apply md:flex-grow hover:ring rounded;
+  }
+}
+`,
+      "utf-8",
+    );
+
+    const ctx = createContext(tmpDir);
+    const css = generateAppCss(ctx);
+
+    expect(css).toContain("md:grow");
+    expect(css).toContain("hover:ring-3");
+    expect(css).not.toContain("md:flex-grow");
+    expect(css).not.toMatch(/hover:ring(?!-3)/);
+  });
+});

package/scripts/migrate/templates/app-css.ts

@@ -1,7 +1,26 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { MigrationContext } from "../types";
+import { log } from "../types";
 import type { ExtractedTheme } from "../analyzers/theme-extractor";
+import { fixOklchHexMismatches, isOklchCoordinates } from "../transforms/color-oklch";
+import { transformCss } from "../transforms/css";
+import { renameToken } from "../transforms/tailwind-renames";
+
+const GRAY_SHADES = ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"];
+const GRAY_SCALE_DEFAULTS: Record<string, string> = {
+  "50": "#f9fafb",
+  "100": "#f3f4f6",
+  "200": "#e5e7eb",
+  "300": "#d1d5db",
+  "400": "#9ca3af",
+  "500": "#6b7280",
+  "600": "#4b5563",
+  "700": "#374151",
+  "800": "#1f2937",
+  "900": "#111827",
+  "950": "#030712",
+};
 
 /**
  * Find the original site's custom CSS file.
@@ -48,41 +67,20 @@ function extractCustomCss(rawCss: string): string {
 /**
  * Transform @apply directives for TW3→TW4 compatibility.
  * The tailwind.ts transform handles className= attributes in JSX,
- * but @apply inside CSS also needs class renames.
- *
- * Also converts @apply with custom brand/theme colors to native CSS
- * properties when the utility class might not be registered in TW4.
+ * but @apply inside CSS also needs the same class renames — reuses the
+ * single shared table (transforms/tailwind-renames.ts) so this never
+ * drifts from the className= rewriter again.
  */
 function transformApplyDirectives(css: string): string {
-  return css
-    .replace(/@apply\s+([^;]+);/g, (_match, classes: string) => {
-      let fixed = classes;
-      // flex-grow-0 → grow-0
-      fixed = fixed.replace(/\bflex-grow-0\b/g, "grow-0");
-      fixed = fixed.replace(/\bflex-grow\b/g, "grow");
-      fixed = fixed.replace(/\bflex-shrink-0\b/g, "shrink-0");
-      fixed = fixed.replace(/\bflex-shrink\b/g, "shrink");
-      // transform → removed (auto in v4)
-      fixed = fixed.replace(/\btransform\b(?!-none)/g, "");
-      fixed = fixed.replace(/\bfilter\b/g, "");
-      // ring → ring-3
-      fixed = fixed.replace(/\bring\b(?!-)/g, "ring-3");
-      // Clean up multiple spaces
-      fixed = fixed.replace(/\s{2,}/g, " ").trim();
-      return `@apply ${fixed};`;
-    });
-}
-
-/**
- * Test if a value looks like oklch coordinates (space-separated numbers,
- * possibly with `/` for alpha). Examples: "0.5 0.2 30", "0.8 0.15 120 / 0.5"
- * This distinguishes oklch coordinate values from hex colors.
- */
-function isOklchCoordinates(val: string): boolean {
-  const trimmed = val.trim();
-  // oklch coordinates: 2-3 space-separated numbers, possibly with / alpha
-  // e.g. "0.5 0.2 30" or "0.85 0.15 120 / 0.5"
-  return /^[\d.]+\s+[\d.]+\s+[\d.]+(\s*\/\s*[\d.]+)?$/.test(trimmed);
+  return css.replace(/@apply\s+([^;]+);/g, (_match, classes: string) => {
+    const fixed = classes
+      .split(/\s+/)
+      .filter(Boolean)
+      .map(renameToken)
+      .filter(Boolean)
+      .join(" ");
+    return `@apply ${fixed};`;
+  });
 }
 
 /**
@@ -203,22 +201,57 @@ ${colorLines}
     }
   }
 
-  // Gray scale compat (Tailwind v3 had gray-50..gray-950 by default)
+  // Port theme.extend.colors / theme.extend.fontFamily / theme.extend.screens
+  // from the source site's tailwind.config.ts (extracted in phase-analyze
+  // before that file is deleted — see analyzers/tailwind-config.ts). Without
+  // this, custom brand palettes and named font stacks are silently dropped
+  // and any class referencing them (`bg-perola`, `font-bebas-neue`) makes
+  // Tailwind v4 throw "Cannot apply unknown utility class" (decocms/blocks#369).
+  // gray-50..950 are handled below, in the gray-scale block, so a custom
+  // gray ramp from tailwind.config.ts overrides the default instead of
+  // being declared twice in the same @theme rule (last declaration wins in
+  // CSS — the default would otherwise silently clobber the custom one).
+  const twColors = ctx.tailwindConfig.colors;
+  const twColorKeys = Object.keys(twColors).filter(
+    (k) => !(`--color-${k}` in semanticColors) && !GRAY_SHADES.some((shade) => k === `gray-${shade}`),
+  );
+  if (twColorKeys.length > 0) {
+    themeBlock += `\n\n  /* Custom colors ported from tailwind.config.ts */`;
+    for (const key of twColorKeys) {
+      themeBlock += `\n  --color-${key}: ${twColors[key]};`;
+    }
+  }
+
+  const twFontFamily = ctx.tailwindConfig.fontFamily;
+  const twFontKeys = Object.keys(twFontFamily);
+  if (twFontKeys.length > 0) {
+    themeBlock += `\n\n  /* Font stacks ported from tailwind.config.ts */`;
+    for (const key of twFontKeys) {
+      themeBlock += `\n  --font-${key}: ${twFontFamily[key]};`;
+    }
+  }
+
+  const twScreens = ctx.tailwindConfig.screens;
+  const twScreenKeys = Object.keys(twScreens);
+  if (twScreenKeys.length > 0) {
+    themeBlock += `\n\n  /* Custom breakpoints ported from tailwind.config.ts */`;
+    for (const key of twScreenKeys) {
+      themeBlock += `\n  --breakpoint-${key}: ${twScreens[key]};`;
+    }
+  }
+
+  // Gray scale compat (Tailwind v3 had gray-50..gray-950 by default) — uses
+  // the site's own tailwind.config.ts gray-* override when present, falling
+  // back to the v3 default otherwise.
   themeBlock += `
 
-  /* Gray scale (Tailwind v3 default, required for bg-gray-*, text-gray-*, etc.) */
-  --color-gray-50: #f9fafb;
-  --color-gray-100: #f3f4f6;
-  --color-gray-200: #e5e7eb;
-  --color-gray-300: #d1d5db;
-  --color-gray-400: #9ca3af;
-  --color-gray-500: #6b7280;
-  --color-gray-600: #4b5563;
-  --color-gray-700: #374151;
-  --color-gray-800: #1f2937;
-  --color-gray-900: #111827;
-  --color-gray-950: #030712;
-}`;
+  /* Gray scale (Tailwind v3 default, required for bg-gray-*, text-gray-*, etc.) */`;
+  for (const shade of GRAY_SHADES) {
+    const key = `gray-${shade}`;
+    const value = twColors[key] ?? GRAY_SCALE_DEFAULTS[shade];
+    themeBlock += `\n  --color-${key}: ${value};`;
+  }
+  themeBlock += `\n}`;
   sections.push(themeBlock);
 
   // ── DaisyUI v5 compat ─────────────────────────────────────────────
@@ -345,22 +378,79 @@ section[data-deferred="true"] {
   display: none;
 }`);
 
+  // ── Safelist (tailwind.config.ts) ──────────────────────────────────
+  // Tailwind v4 has no config-based safelist. Literal class names port
+  // directly to `@source inline(...)`; regex patterns can't be converted
+  // automatically and are flagged for manual review instead.
+  const safelist = ctx.tailwindConfig.safelist;
+  if (safelist.length > 0) {
+    sections.push(`/* Safelist ported from tailwind.config.ts (Tailwind v4 has no config safelist) */
+@source inline("${safelist.join(" ")}");`);
+  }
+  for (const pattern of ctx.tailwindConfig.safelistPatterns) {
+    ctx.manualReviewItems.push({
+      file: "src/styles/app.css",
+      reason: `tailwind.config.ts safelist pattern ${pattern} cannot be auto-converted — add the matching classes via @source inline("...") manually (Tailwind v4 has no regex safelist)`,
+      severity: "warning",
+    });
+  }
+
+  // Fix gotcha #43: `oklch(var(--x))` is emitted wherever a CMS theme var
+  // looked like bare oklch coordinates, but if that var was actually
+  // declared as hex elsewhere, the wrapper is invalid CSS (icons/fills
+  // silently render black). Convert the hex declaration to an oklch triplet
+  // so the wrapper stays valid.
+  //
+  // Scoped to the generator's OWN output (`sections` so far) — NOT the
+  // site's original custom CSS appended below. That content should be
+  // passed through as close to verbatim as possible; scanning/rewriting it
+  // too would mean silently mutating a site-authored `--x: #hex;`
+  // declaration if the site happens to also use the same
+  // `oklch(var(--x))` idiom for an unrelated purpose.
+  const generatorCss = sections.join("\n\n") + "\n";
+  const { css: fixedGeneratorCss, fixed, flagged } = fixOklchHexMismatches(generatorCss);
+  for (const note of fixed) {
+    log(ctx, `[app.css] Fixed oklch/hex mismatch: ${note}`);
+  }
+  for (const note of flagged) {
+    ctx.manualReviewItems.push({
+      file: "src/styles/app.css",
+      reason: note,
+      severity: "warning",
+    });
+  }
+
   // ── Incorporate original site's custom CSS ────────────────────
   // Instead of throwing away the site's CSS, we extract and append
   // all custom rules (component overrides, @layer base, @font-face,
-  // typography utilities, feature-specific CSS, etc.)
+  // typography utilities, feature-specific CSS, etc.). Appended AFTER the
+  // oklch fix above runs, so this content is never scanned/rewritten by it.
   const originalCss = findOriginalCss(ctx);
+  let originalCssBlock = "";
   if (originalCss) {
     const customCss = extractCustomCss(originalCss);
     if (customCss) {
-      const transformed = transformApplyDirectives(customCss);
-      sections.push(`/* ═══════════════════════════════════════════════════════════════
+      let transformed = transformApplyDirectives(customCss);
+      const cssFix = transformCss(transformed);
+      transformed = cssFix.css;
+      for (const note of cssFix.notes) {
+        if (note.startsWith("MANUAL:")) {
+          ctx.manualReviewItems.push({
+            file: "src/styles/app.css",
+            reason: note.replace(/^MANUAL:\s*/, ""),
+            severity: "warning",
+          });
+        } else {
+          log(ctx, `[app.css] ${note}`);
+        }
+      }
+      originalCssBlock = `/* ═══════════════════════════════════════════════════════════════
    Original site CSS (migrated from tailwind.css)
    ═══════════════════════════════════════════════════════════════ */
 
-${transformed}`);
+${transformed}`;
     }
   }
 
-  return sections.join("\n\n") + "\n";
+  return originalCssBlock ? `${fixedGeneratorCss}\n${originalCssBlock}\n` : fixedGeneratorCss;
 }

package/scripts/migrate/templates/hooks.test.ts

@@ -12,6 +12,7 @@ function makeCtx(platform: MigrationContext["platform"]): MigrationContext {
 		importMap: {},
 		discoveredNpmDeps: {},
 		themeColors: {},
+	tailwindConfig: { colors: {}, fontFamily: {}, screens: {}, safelist: [], safelistPatterns: [], plugins: [], reviewItems: [] },
 		fontFamily: null,
 		files: [],
 		sectionMetas: [],

package/scripts/migrate/templates/package-json.ts

@@ -174,6 +174,11 @@ export function generatePackageJson(ctx: MigrationContext): string {
     devDependencies: {
       "@cloudflare/vite-plugin": "^1.27.0",
       "@decocms/blocks-cli": `^${frameworkVersion}`,
+      // CLI build of src/styles/app.css — used by the migration's own
+      // css-compile-check.ts (phase-compile) and by `tailwind:lint`, so a
+      // dropped custom theme token fails migration/CI instead of shipping
+      // an unstyled page (decocms/blocks#369).
+      "@tailwindcss/cli": "^4.2.1",
       "@tailwindcss/vite": "^4.2.1",
       "@tanstack/router-cli": "1.166.7",
       "@types/react": "^19.2.14",

package/scripts/migrate/templates/server-entry-vtex-invoke.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { createContext } from "../types";
+import type { MigrationContext } from "../types";
+import { generateServerEntry } from "./server-entry";
+
+/**
+ * Regression guard for #368: createUseUser/createUseWishlist
+ * (@decocms/apps-vtex/hooks) require invoke.vtex.loaders.user/wishlist and
+ * invoke.vtex.actions.addToWishlist/removeFromWishlist. Before this fix, the
+ * scaffolded invoke only wired `vtex.actions` from invoke.gen.ts, so any
+ * scaffolded site rendering useUser()/useWishlist() crashed the Header on
+ * mount (`Cannot read properties of undefined (reading 'user')`).
+ */
+function makeVtexCtx(): MigrationContext {
+  const ctx = createContext("/tmp/vtex-invoke-scaffold-fixture-site");
+  ctx.siteName = "acme-storefront";
+  ctx.platform = "vtex";
+  ctx.vtexAccount = "acme";
+  return ctx;
+}
+
+describe("VTEX invoke scaffold wires vtex.loaders + wishlist actions (#368)", () => {
+  const files = generateServerEntry(makeVtexCtx());
+  const invokeSrc = files["src/server/invoke.ts"];
+
+  it("scaffolds invoke.vtex.loaders.user and invoke.vtex.loaders.wishlist", () => {
+    expect(invokeSrc).toContain("loaders: {");
+    expect(invokeSrc).toContain("user: _vtexUser");
+    expect(invokeSrc).toContain("wishlist: _vtexWishlist");
+  });
+
+  it("scaffolds invoke.vtex.actions.addToWishlist and removeFromWishlist", () => {
+    expect(invokeSrc).toContain("addToWishlist: _addToWishlist");
+    expect(invokeSrc).toContain("removeFromWishlist: _removeFromWishlist");
+  });
+
+  it("still spreads the generated checkout/session/masterData/newsletter actions", () => {
+    expect(invokeSrc).toContain("...vtexActions,");
+  });
+
+  it("imports getUser/getWishlist/addItem/removeItem from @decocms/apps-vtex", () => {
+    expect(invokeSrc).toContain('from "@decocms/apps-vtex/loaders/user"');
+    expect(invokeSrc).toContain('from "@decocms/apps-vtex/loaders/wishlist"');
+    expect(invokeSrc).toContain('from "@decocms/apps-vtex/actions/wishlist"');
+  });
+
+  it("derives shopperId from the auth JWT instead of a hardcoded value", () => {
+    expect(invokeSrc).toContain("getShopperId");
+    expect(invokeSrc).toContain("parseVtexAuthJwt");
+  });
+});

package/scripts/migrate/templates/server-entry.ts

@@ -326,8 +326,12 @@ ${hasVtexAuthLoader ? `import vtexAuthLoader from "../loaders/vtex-auth-loader";
   performVtexLogout,
   parseVtexAuthJwt,
 } from "@decocms/apps-vtex/utils/authHelpers";
+import { getUser, type Person } from "@decocms/apps-vtex/loaders/user";
+import { getWishlist, type WishlistItem } from "@decocms/apps-vtex/loaders/wishlist";
+import { addItem as addToWishlistItem, removeItem as removeFromWishlistItem } from "@decocms/apps-vtex/actions/wishlist";
 
 export type { OrderForm } from "./invoke.gen";
+export type { Person, WishlistItem };
 
 function getVtexCookies(): string {
   return extractVtexCookiesFromHeader(getRequestHeader("cookie") ?? "");
@@ -361,9 +365,57 @@ const _getUserFromJwt = createServerFn({ method: "POST" }).handler(
   },
 );
 
+// createUseUser/createUseWishlist (@decocms/apps-vtex/hooks) require
+// invoke.vtex.loaders.user/wishlist and invoke.vtex.actions.addToWishlist/
+// removeFromWishlist — without these the hooks throw on mount and take
+// down the whole section (e.g. the Header) via the error boundary.
+function getShopperId(): string | null {
+  return parseVtexAuthJwt(getRequestHeader("cookie") ?? "")?.email ?? null;
+}
+
+const _vtexUser = createServerFn({ method: "GET" }).handler(
+  async (): Promise<Person | null> => {
+    return getUser(getVtexCookies());
+  },
+);
+
+const _vtexWishlist = createServerFn({ method: "GET" }).handler(
+  async (): Promise<WishlistItem[]> => {
+    const shopperId = getShopperId();
+    if (!shopperId) return [];
+    return getWishlist(getVtexCookies(), { shopperId, allRecords: true });
+  },
+);
+
+const _addToWishlist = createServerFn({ method: "POST" })
+  .inputValidator(
+    (data: { data: { productId: string; sku: string; title?: string } }) => data,
+  )
+  .handler(async ({ data }): Promise<WishlistItem[]> => {
+    const shopperId = getShopperId();
+    if (!shopperId) throw new Error("User must be logged in to add to wishlist");
+    return addToWishlistItem(data.data, shopperId, getVtexCookies());
+  });
+
+const _removeFromWishlist = createServerFn({ method: "POST" })
+  .inputValidator((data: { data: { id: string } }) => data)
+  .handler(async ({ data }): Promise<WishlistItem[]> => {
+    const shopperId = getShopperId();
+    if (!shopperId) throw new Error("User must be logged in to remove from wishlist");
+    return removeFromWishlistItem(data.data.id, shopperId, getVtexCookies());
+  });
+
 export const invoke = {
   vtex: {
-    actions: vtexActions,
+    actions: {
+      ...vtexActions,
+      addToWishlist: _addToWishlist,
+      removeFromWishlist: _removeFromWishlist,
+    },
+    loaders: {
+      user: _vtexUser,
+      wishlist: _vtexWishlist,
+    },
   },
   site: {
     loaders: {

package/scripts/migrate/transforms/color-oklch.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { fixOklchHexMismatches, hexToOklchTriplet, isOklchCoordinates } from "./color-oklch";
+
+describe("isOklchCoordinates", () => {
+  it("matches bare oklch triplets", () => {
+    expect(isOklchCoordinates("0.55 0.2 30")).toBe(true);
+    expect(isOklchCoordinates("0.85 0.15 120 / 0.5")).toBe(true);
+  });
+
+  it("rejects hex and other color syntaxes", () => {
+    expect(isOklchCoordinates("#B10200")).toBe(false);
+    expect(isOklchCoordinates("rgb(1, 2, 3)")).toBe(false);
+  });
+});
+
+describe("hexToOklchTriplet", () => {
+  it("converts white to L=1 C=0", () => {
+    const triplet = hexToOklchTriplet("#ffffff");
+    expect(triplet).not.toBeNull();
+    const [l, c] = triplet!.split(" ").map(Number);
+    expect(l).toBeCloseTo(1, 2);
+    expect(c).toBeCloseTo(0, 2);
+  });
+
+  it("converts black to L=0 C=0", () => {
+    const triplet = hexToOklchTriplet("#000000");
+    expect(triplet).not.toBeNull();
+    const [l, c] = triplet!.split(" ").map(Number);
+    expect(l).toBeCloseTo(0, 2);
+    expect(c).toBeCloseTo(0, 2);
+  });
+
+  it("expands 3-digit hex", () => {
+    expect(hexToOklchTriplet("#fff")).toBe(hexToOklchTriplet("#ffffff"));
+  });
+
+  it("returns null for unparseable input", () => {
+    expect(hexToOklchTriplet("not-a-color")).toBeNull();
+  });
+});
+
+describe("fixOklchHexMismatches", () => {
+  it("converts a hex-declared var used as oklch(var(--x)) into an oklch triplet", () => {
+    const css = `:root {
+  --icon-color: #B10200;
+}
+.icon {
+  fill: oklch(var(--icon-color));
+}`;
+
+    const result = fixOklchHexMismatches(css);
+    expect(result.fixed.length).toBe(1);
+    expect(result.css).toMatch(/--icon-color:\s*[\d.]+\s+[\d.]+\s+[\d.]+;/);
+    expect(result.css).not.toContain("#B10200");
+  });
+
+  it("leaves already-valid oklch coordinate declarations untouched", () => {
+    const css = `:root {
+  --icon-color: 0.55 0.2 30;
+}
+.icon {
+  fill: oklch(var(--icon-color));
+}`;
+
+    const result = fixOklchHexMismatches(css);
+    expect(result.fixed).toEqual([]);
+    expect(result.flagged).toEqual([]);
+    expect(result.css).toBe(css);
+  });
+
+  it("flags rgb()-declared vars used as oklch(var(--x)) instead of guessing", () => {
+    const css = `:root {
+  --icon-color: rgb(10, 20, 30);
+}
+.icon {
+  fill: oklch(var(--icon-color));
+}`;
+
+    const result = fixOklchHexMismatches(css);
+    expect(result.fixed).toEqual([]);
+    expect(result.flagged.length).toBe(1);
+  });
+});