@decocms/blocks-cli 7.21.0 → 7.22.0

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

@@ -0,0 +1,122 @@
+/**
+ * hex -> oklch triplet conversion + a post-process pass that fixes gotcha #43:
+ * generated CSS emits `oklch(var(--x))` (daisyUI v5's opacity-modifier
+ * pattern) but `--x` was assigned a hex color, not oklch coordinates.
+ * `oklch(#B10200)` is invalid CSS — the color silently falls back to its
+ * initial value, which is why SVG icons using `fill: oklch(var(--icon-color))`
+ * render solid black on migrated sites.
+ */
+
+/**
+ * True if `value` looks like bare oklch coordinates: 2-3 space-separated
+ * numbers, optionally with a `/ alpha` suffix. E.g. "0.55 0.2 30" or
+ * "0.85 0.15 120 / 0.5". Distinguishes oklch coordinate values from hex
+ * colors or other CSS color syntaxes.
+ */
+export function isOklchCoordinates(value: string): boolean {
+  const trimmed = value.trim();
+  return /^[\d.]+\s+[\d.]+\s+[\d.]+(\s*\/\s*[\d.]+)?$/.test(trimmed);
+}
+
+function srgbChannelToLinear(c: number): number {
+  const v = c / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+}
+
+/**
+ * Convert a hex color (#rgb, #rrggbb, #rrggbbaa) to an oklch coordinate
+ * triplet string "L C H" (L in [0,1], C in [0, ~0.4], H in degrees
+ * [0, 360)), matching the format expected by `oklch(var(--x))`.
+ * Returns null if the input isn't a parseable hex color.
+ */
+export function hexToOklchTriplet(hex: string): string | null {
+  const normalized = hex.trim().replace(/^#/, "");
+  let r: number, g: number, b: number;
+
+  if (normalized.length === 3) {
+    r = parseInt(normalized[0] + normalized[0], 16);
+    g = parseInt(normalized[1] + normalized[1], 16);
+    b = parseInt(normalized[2] + normalized[2], 16);
+  } else if (normalized.length === 6 || normalized.length === 8) {
+    r = parseInt(normalized.slice(0, 2), 16);
+    g = parseInt(normalized.slice(2, 4), 16);
+    b = parseInt(normalized.slice(4, 6), 16);
+  } else {
+    return null;
+  }
+  if ([r, g, b].some((c) => Number.isNaN(c))) return null;
+
+  const lr = srgbChannelToLinear(r);
+  const lg = srgbChannelToLinear(g);
+  const lb = srgbChannelToLinear(b);
+
+  // linear sRGB -> LMS (Björn Ottosson's OKLab matrices)
+  const l = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb;
+  const m = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb;
+  const s = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb;
+
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+
+  const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  const b_ = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+
+  const C = Math.sqrt(a * a + b_ * b_);
+  let H = (Math.atan2(b_, a) * 180) / Math.PI;
+  if (H < 0) H += 360;
+
+  return `${L.toFixed(4)} ${C.toFixed(4)} ${H.toFixed(2)}`;
+}
+
+/**
+ * Scan generated CSS for `oklch(var(--x))` usages, look up how `--x` was
+ * declared elsewhere in the same stylesheet, and rewrite hex-valued
+ * declarations to oklch triplets so the wrapper stays valid CSS.
+ * rgb()/hsl()/named-color declarations are left as-is and reported so a
+ * human can convert them (no lossless closed-form conversion is attempted
+ * for those here).
+ */
+export function fixOklchHexMismatches(css: string): { css: string; fixed: string[]; flagged: string[] } {
+  const declRe = /(--[\w-]+)\s*:\s*([^;]+);/g;
+  const declaredValues = new Map<string, string>();
+  let m: RegExpExecArray | null;
+  while ((m = declRe.exec(css)) !== null) {
+    declaredValues.set(m[1], m[2].trim());
+  }
+
+  const usageRe = /oklch\(var\((--[\w-]+)\)\)/g;
+  const fixed: string[] = [];
+  const flagged: string[] = [];
+  let result = css;
+
+  const seen = new Set<string>();
+  let usageMatch: RegExpExecArray | null;
+  while ((usageMatch = usageRe.exec(css)) !== null) {
+    const varName = usageMatch[1];
+    if (seen.has(varName)) continue;
+    seen.add(varName);
+
+    const value = declaredValues.get(varName);
+    if (!value || isOklchCoordinates(value)) continue;
+
+    const hexMatch = value.match(/^#[0-9a-fA-F]{3,8}$/);
+    if (hexMatch) {
+      const triplet = hexToOklchTriplet(value);
+      if (triplet) {
+        const declPattern = new RegExp(
+          `(${varName.replace(/[-]/g, "\\-")}\\s*:\\s*)${value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s*;)`,
+          "g",
+        );
+        result = result.replace(declPattern, `$1${triplet}$2`);
+        fixed.push(`${varName}: ${value} -> oklch triplet ${triplet}`);
+      }
+      continue;
+    }
+
+    flagged.push(`${varName} is used as oklch(var(${varName})) but declared as "${value}" — not a hex or oklch-coordinate value; convert manually`);
+  }
+
+  return { css: result, fixed, flagged };
+}

package/scripts/migrate/transforms/css.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { promoteApplyClassesToUtility, rewriteThemeHelper, transformCss } from "./css";
+
+describe("rewriteThemeHelper", () => {
+  it("rewrites theme(colors.x.y) to var(--color-x-y)", () => {
+    const r = rewriteThemeHelper(".foo { color: theme(colors.gray.100); }");
+    expect(r.css).toBe(".foo { color: var(--color-gray-100); }");
+    expect(r.notes.length).toBe(1);
+  });
+
+  it("rewrites theme(spacing.4) to var(--spacing-4)", () => {
+    const r = rewriteThemeHelper(".foo { margin: theme(spacing.4); }");
+    expect(r.css).toBe(".foo { margin: var(--spacing-4); }");
+  });
+
+  it("preserves a fallback second argument", () => {
+    const r = rewriteThemeHelper(".foo { color: theme(colors.gray.100, #fff); }");
+    expect(r.css).toBe(".foo { color: var(--color-gray-100, #fff); }");
+  });
+
+  it("leaves a bare theme() call without a dotted path untouched", () => {
+    const r = rewriteThemeHelper(".foo { color: theme(primary); }");
+    expect(r.css).toBe(".foo { color: theme(primary); }");
+  });
+});
+
+describe("promoteApplyClassesToUtility", () => {
+  it("promotes a single-class @apply rule from @layer components to @utility", () => {
+    const css = `@layer components {
+  .btn-primary {
+    @apply px-4 py-2 bg-red-500;
+  }
+}`;
+    const r = promoteApplyClassesToUtility(css);
+    expect(r.css).toContain("@utility btn-primary {");
+    expect(r.css).not.toContain("@layer components");
+    expect(r.notes.some((n) => n.includes("Promoted"))).toBe(true);
+  });
+
+  it("keeps compound selectors inside @layer components and flags them", () => {
+    const css = `@layer components {
+  .card .card-title {
+    @apply text-lg font-bold;
+  }
+}`;
+    const r = promoteApplyClassesToUtility(css);
+    expect(r.css).toContain("@layer components");
+    expect(r.css).toContain(".card .card-title");
+    expect(r.notes.some((n) => n.startsWith("MANUAL:"))).toBe(true);
+  });
+
+  it("promotes some rules and keeps others in the same @layer block", () => {
+    const css = `@layer components {
+  .btn-primary {
+    @apply px-4 bg-red-500;
+  }
+  .card .title {
+    @apply text-lg;
+  }
+}`;
+    const r = promoteApplyClassesToUtility(css);
+    expect(r.css).toContain("@utility btn-primary {");
+    expect(r.css).toContain("@layer components");
+    expect(r.css).toContain(".card .title");
+  });
+
+  it("passes through a comment-only @layer components block instead of dropping it", () => {
+    const css = `@layer components {
+  /* keep tab styles centralized here for now */
+}
+
+.after { color: red; }`;
+    const r = promoteApplyClassesToUtility(css);
+    expect(r.css).toContain("@layer components");
+    expect(r.css).toContain("/* keep tab styles centralized here for now */");
+    expect(r.css).toContain(".after { color: red; }");
+  });
+
+  it("passes through an empty @layer components block instead of dropping it", () => {
+    const css = `@layer components {
+}
+
+.after { color: red; }`;
+    const r = promoteApplyClassesToUtility(css);
+    expect(r.css).toContain("@layer components");
+    expect(r.css).toContain(".after { color: red; }");
+  });
+
+  it("is a no-op when there is no @layer components block", () => {
+    const css = ".foo { color: red; }";
+    const r = promoteApplyClassesToUtility(css);
+    expect(r.css).toBe(css);
+    expect(r.notes).toEqual([]);
+  });
+});
+
+describe("transformCss", () => {
+  it("applies both fixes in sequence", () => {
+    const css = `@layer components {
+  .btn-brand {
+    @apply px-4;
+    color: theme(colors.brand.500);
+  }
+}`;
+    const r = transformCss(css);
+    expect(r.css).toContain("@utility btn-brand {");
+    expect(r.css).toContain("var(--color-brand-500)");
+  });
+});

package/scripts/migrate/transforms/css.ts

@@ -0,0 +1,186 @@
+/**
+ * Raw-CSS transforms for the Tailwind v3 -> v4 migration, applied to the
+ * source site's custom CSS before it's appended to the generated
+ * `src/styles/app.css` (see templates/app-css.ts).
+ *
+ * Covers two gotchas from the migration skill (references/css-styling.md):
+ *   - the v3 `theme()` CSS helper function is gone in v4 — CSS-first config
+ *     means theme values live as custom properties, so `theme(colors.x.y)`
+ *     must become `var(--color-x-y)` (gotcha referenced alongside #48).
+ *   - a custom class defined under `@layer components { .foo { @apply ...; } }`
+ *     that other code `@apply`s or applies a variant to doesn't reliably
+ *     participate in v4's utility pipeline — it needs to be a `@utility`
+ *     (gotcha #49).
+ */
+
+export interface CssTransformResult {
+  css: string;
+  notes: string[];
+}
+
+// Maps a `theme()` path's first segment (Tailwind v3 `theme.colors`/
+// `theme.extend.*` keys) to the CSS custom property prefix Tailwind v4
+// generates for it under `@theme`.
+const THEME_CATEGORY_TO_VAR_PREFIX: Record<string, string> = {
+  colors: "color",
+  color: "color",
+  spacing: "spacing",
+  fontFamily: "font",
+  fontSize: "text",
+  fontWeight: "font-weight",
+  borderRadius: "radius",
+  screens: "breakpoint",
+  zIndex: "z",
+  boxShadow: "shadow",
+  letterSpacing: "tracking",
+  lineHeight: "leading",
+};
+
+/**
+ * Rewrite `theme(colors.gray.100)` -> `var(--color-gray-100)`,
+ * `theme(spacing.4)` -> `var(--spacing-4)`, with fallback support:
+ * `theme(colors.gray.100, #fff)` -> `var(--color-gray-100, #fff)`.
+ * Unknown categories keep their name verbatim as the var prefix so the
+ * rewrite is still valid CSS even if not a perfect v4 token match.
+ */
+export function rewriteThemeHelper(css: string): CssTransformResult {
+  const notes: string[] = [];
+  const re = /\btheme\(\s*(['"]?)([\w.-]+)\1\s*(?:,\s*([^)]+))?\)/g;
+
+  const result = css.replace(re, (match, _quote, dottedPath, fallback) => {
+    const [category, ...rest] = dottedPath.split(".");
+    if (rest.length === 0) return match; // not a category.path reference, leave alone
+
+    const prefix = THEME_CATEGORY_TO_VAR_PREFIX[category] ?? category;
+    const varName = `--${prefix}-${rest.join("-")}`;
+    const replacement = fallback ? `var(${varName}, ${fallback.trim()})` : `var(${varName})`;
+    notes.push(`theme(${dottedPath}) -> var(${varName})`);
+    return replacement;
+  });
+
+  return { css: result, notes };
+}
+
+/**
+ * Find the span of a balanced-brace block starting at `openBraceIndex`
+ * (the index of the `{`). Returns the index just after the matching `}`.
+ */
+function findMatchingBrace(css: string, openBraceIndex: number): number {
+  let depth = 0;
+  for (let i = openBraceIndex; i < css.length; i++) {
+    if (css[i] === "{") depth++;
+    else if (css[i] === "}") {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+  }
+  return css.length;
+}
+
+interface CssRule {
+  selector: string;
+  body: string;
+}
+
+/** Split the contents of a CSS block into its top-level rules (selector + brace-balanced body). */
+function splitTopLevelRules(blockContent: string): CssRule[] {
+  const rules: CssRule[] = [];
+  let i = 0;
+  while (i < blockContent.length) {
+    const braceIdx = blockContent.indexOf("{", i);
+    if (braceIdx === -1) break;
+    const selector = blockContent.slice(i, braceIdx).trim();
+    const end = findMatchingBrace(blockContent, braceIdx);
+    const body = blockContent.slice(braceIdx + 1, end - 1);
+    if (selector) rules.push({ selector, body });
+    i = end;
+  }
+  return rules;
+}
+
+const SINGLE_CLASS_SELECTOR = /^\.([\w-]+)$/;
+
+/**
+ * Promote single-class rules inside `@layer components { ... }` to
+ * top-level `@utility` blocks, which is what Tailwind v4 requires for a
+ * custom class to be `@apply`-able / variant-composable elsewhere. Rules
+ * with compound/multi-part selectors (`.foo .bar`, `.foo, .baz`) can't be
+ * mechanically promoted — they're left inside `@layer components` and
+ * flagged for manual review.
+ */
+export function promoteApplyClassesToUtility(css: string): CssTransformResult {
+  const notes: string[] = [];
+  const layerRe = /@layer\s+components\s*\{/g;
+  let result = "";
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+
+  while ((match = layerRe.exec(css)) !== null) {
+    const blockStart = match.index;
+    const braceIdx = match.index + match[0].length - 1;
+    const blockEnd = findMatchingBrace(css, braceIdx);
+    const inner = css.slice(braceIdx + 1, blockEnd - 1);
+
+    result += css.slice(cursor, blockStart);
+
+    const rules = splitTopLevelRules(inner);
+
+    // A block with no top-level `selector { ... }` rule (empty, or only
+    // comments/at-rules) has nothing to promote or re-wrap — pass it
+    // through verbatim instead of silently dropping it, since `promoted`
+    // and `remaining` would otherwise both stay empty and nothing gets
+    // appended to `result` for this block at all.
+    if (rules.length === 0) {
+      result += css.slice(blockStart, blockEnd);
+      cursor = blockEnd;
+      layerRe.lastIndex = blockEnd;
+      continue;
+    }
+
+    const promoted: string[] = [];
+    const remaining: CssRule[] = [];
+
+    for (const rule of rules) {
+      const singleClass = rule.selector.match(SINGLE_CLASS_SELECTOR);
+      if (singleClass && rule.body.includes("@apply")) {
+        promoted.push(`@utility ${singleClass[1]} {${rule.body}}`);
+        notes.push(`Promoted .${singleClass[1]} from @layer components to @utility ${singleClass[1]} (Tailwind v4 requires this for @apply-ability)`);
+      } else {
+        remaining.push(rule);
+        if (rule.body.includes("@apply")) {
+          notes.push(`MANUAL: .${rule.selector} in @layer components uses @apply but has a compound selector — cannot auto-promote to @utility, verify it still resolves in Tailwind v4`);
+        }
+      }
+    }
+
+    result += promoted.join("\n\n");
+    if (promoted.length > 0 && remaining.length > 0) result += "\n\n";
+    if (remaining.length > 0) {
+      const remainingBody = remaining.map((r) => `  ${r.selector} {${r.body}}`).join("\n\n");
+      result += `@layer components {\n${remainingBody}\n}`;
+    }
+
+    cursor = blockEnd;
+    layerRe.lastIndex = blockEnd;
+  }
+
+  result += css.slice(cursor);
+
+  return { css: result, notes };
+}
+
+/** Run both raw-CSS transforms in sequence. */
+export function transformCss(css: string): CssTransformResult {
+  const notes: string[] = [];
+  let result = css;
+
+  const themeFix = rewriteThemeHelper(result);
+  result = themeFix.css;
+  notes.push(...themeFix.notes);
+
+  const utilityFix = promoteApplyClassesToUtility(result);
+  result = utilityFix.css;
+  notes.push(...utilityFix.notes);
+
+  return { css: result, notes };
+}

package/scripts/migrate/transforms/tailwind-renames.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { renameToken } from "./tailwind-renames";
+
+describe("renameToken", () => {
+  it("renames a bare utility with no modifier prefix", () => {
+    expect(renameToken("flex-grow")).toBe("grow");
+    expect(renameToken("ring")).toBe("ring-3");
+  });
+
+  it("preserves a single modifier prefix when renaming", () => {
+    expect(renameToken("md:flex-grow")).toBe("md:grow");
+    expect(renameToken("hover:ring")).toBe("hover:ring-3");
+  });
+
+  it("preserves a stacked modifier chain when renaming", () => {
+    expect(renameToken("dark:hover:ring")).toBe("dark:hover:ring-3");
+  });
+
+  it("renames a DaisyUI class behind a modifier prefix", () => {
+    expect(renameToken("hover:badge-ghost")).toBe("hover:badge-soft");
+  });
+
+  it("removes a class (and its modifier prefix) entirely when v4 drops it (e.g. transform is now automatic)", () => {
+    expect(renameToken("transform")).toBe("");
+    expect(renameToken("md:transform")).toBe("");
+  });
+
+  it("is a true no-op for an identity rename, even with a modifier prefix", () => {
+    expect(renameToken("transform-none")).toBe("transform-none");
+    expect(renameToken("md:transform-none")).toBe("md:transform-none");
+  });
+
+  it("leaves an unknown class unchanged", () => {
+    expect(renameToken("bg-red-500")).toBe("bg-red-500");
+    expect(renameToken("md:bg-red-500")).toBe("md:bg-red-500");
+  });
+});

package/scripts/migrate/transforms/tailwind-renames.ts

@@ -0,0 +1,224 @@
+/**
+ * Single source of truth for Tailwind v3 -> v4 and DaisyUI v4 -> v5 class
+ * rename tables. Previously these tables were copy-pasted into three
+ * places (`transforms/tailwind.ts`, `templates/app-css.ts`'s `@apply`
+ * rewriter, and the standalone `scripts/tailwind-lint.ts` shipped into
+ * migrated sites) and had drifted out of sync. Import from here instead of
+ * redefining a table.
+ *
+ * Renames are applied via direct map lookup on each already-tokenized
+ * utility class (not sequential string replacement), so scale-shift
+ * entries like `shadow-sm -> shadow-xs` and `shadow -> shadow-sm` can't
+ * cascade into each other in a single pass.
+ */
+
+/** Direct 1:1 Tailwind v3 -> v4 utility class renames. Empty string = remove entirely. */
+export const CLASS_RENAMES: Record<string, string> = {
+  // Flexbox/Grid
+  "flex-grow-0": "grow-0",
+  "flex-grow": "grow",
+  "flex-shrink-0": "shrink-0",
+  "flex-shrink": "shrink",
+
+  // Overflow
+  "overflow-ellipsis": "text-ellipsis",
+
+  // Decoration
+  "decoration-clone": "box-decoration-clone",
+  "decoration-slice": "box-decoration-slice",
+
+  // Transforms (v4 applies transforms automatically — the utility that used
+  // to opt in no longer exists)
+  "transform": "",
+  "transform-gpu": "",
+  "transform-none": "transform-none", // this one stays (explicit disable)
+
+  // Filters (v4 applies automatically)
+  "filter": "",
+  "backdrop-filter": "",
+
+  // Ring width default changed 3px -> 1px; explicit `ring` now means 1px,
+  // so sites relying on the old 3px default need the explicit v3 width.
+  "ring": "ring-3",
+
+  // Outline: v3 `outline-none` (outline: 2px solid transparent, for focus
+  // rings) renamed to `outline-hidden`; v4's new `outline-none` means a
+  // literal `outline: none`.
+  "outline-none": "outline-hidden",
+
+  // Shadow/blur/rounded/drop-shadow scale shifted down one step, with a new
+  // `-xs` step added at the bottom.
+  "shadow-sm": "shadow-xs",
+  "shadow": "shadow-sm",
+  "blur-sm": "blur-xs",
+  "blur": "blur-sm",
+  "rounded-sm": "rounded-xs",
+  "rounded": "rounded-sm",
+  "drop-shadow-sm": "drop-shadow-xs",
+  "drop-shadow": "drop-shadow-sm",
+
+  // Linear gradients renamed to make room for radial-gradient/conic-gradient
+  // utilities.
+  "bg-gradient-to-t": "bg-linear-to-t",
+  "bg-gradient-to-tr": "bg-linear-to-tr",
+  "bg-gradient-to-r": "bg-linear-to-r",
+  "bg-gradient-to-br": "bg-linear-to-br",
+  "bg-gradient-to-b": "bg-linear-to-b",
+  "bg-gradient-to-bl": "bg-linear-to-bl",
+  "bg-gradient-to-l": "bg-linear-to-l",
+  "bg-gradient-to-tl": "bg-linear-to-tl",
+};
+
+/**
+ * DaisyUI v4 -> v5 class renames. Intentionally conservative — only
+ * renames with a confirmed 1:1 replacement are listed here. Structural
+ * breaks that have no mechanical class rename (collapse, btn-group,
+ * form-control — see `detectDaisyUiV5StructuralIssues` below) are flagged
+ * for manual review instead of guessed at.
+ */
+export const DAISYUI_RENAMES: Record<string, string> = {
+  "badge-ghost": "badge-soft",
+  "card-compact": "card-sm",
+};
+
+/**
+ * Rename a single class token, preserving any `modifier:` prefix chain
+ * (`hover:`, `md:`, `dark:`, stacked or not) — e.g. `md:flex-grow` -> `md:grow`,
+ * `hover:ring` -> `hover:ring-3`. Returns `""` if the rename removes the
+ * class entirely (matching v4's dropped `transform`/`filter` utilities),
+ * or the original token unchanged if no rename applies.
+ *
+ * This is the one place that knows how to apply CLASS_RENAMES/DAISYUI_RENAMES
+ * to a token — every caller (JSX className rewriter, @apply rewriter,
+ * tailwind-lint) must go through this instead of doing its own split/lookup,
+ * or a variant-prefixed class silently stops getting renamed (as happened
+ * when the @apply rewriter did a whole-token lookup without stripping the
+ * modifier prefix first).
+ */
+export function renameToken(cls: string): string {
+  const parts = cls.split(":");
+  const utility = parts.pop()!;
+
+  if (CLASS_RENAMES[utility] !== undefined) {
+    const renamed = CLASS_RENAMES[utility];
+    if (renamed === "") return "";
+    if (renamed === utility) return cls;
+    parts.push(renamed);
+    return parts.join(":");
+  }
+
+  if (DAISYUI_RENAMES[utility] && DAISYUI_RENAMES[utility] !== utility) {
+    parts.push(DAISYUI_RENAMES[utility]);
+    return parts.join(":");
+  }
+
+  return cls;
+}
+
+// ── Spacing scale: px → Tailwind unit ───────────────────────────
+export const PX_TO_SPACING: Record<number, string> = {};
+for (let i = 0; i <= 96; i++) {
+  PX_TO_SPACING[i * 4] = String(i);
+}
+PX_TO_SPACING[2] = "0.5";
+PX_TO_SPACING[6] = "1.5";
+PX_TO_SPACING[10] = "2.5";
+PX_TO_SPACING[14] = "3.5";
+
+// Text size: px → native class
+export const TEXT_SIZE_MAP: Record<string, string> = {
+  "12": "xs",
+  "14": "sm",
+  "16": "base",
+  "18": "lg",
+  "20": "xl",
+  "24": "2xl",
+  "30": "3xl",
+  "36": "4xl",
+  "48": "5xl",
+  "60": "6xl",
+  "72": "7xl",
+  "96": "8xl",
+  "128": "9xl",
+};
+
+export interface GotchaFinding {
+  /** Gotcha number in the deco-to-tanstack-migration skill's css-styling.md */
+  gotcha: number;
+  message: string;
+}
+
+/**
+ * Detect DaisyUI v4 classes/patterns with no mechanical v5 replacement —
+ * gotcha #37 (`.collapse` broken under Tailwind v4; `btn-group` and
+ * `form-control` were removed in DaisyUI v5 with no drop-in class rename).
+ * Returns one finding per distinct pattern found in `content`, not one per
+ * occurrence, to avoid flooding the report.
+ */
+export function detectDaisyUiV5StructuralIssues(content: string): GotchaFinding[] {
+  const findings: GotchaFinding[] = [];
+
+  if (/\bcollapse\b/.test(content) && /\bcollapse-(?:title|content)\b/.test(content)) {
+    findings.push({
+      gotcha: 37,
+      message:
+        "DaisyUI .collapse usage found — its expand/collapse chain breaks under Tailwind v4. " +
+        "Replace with native <details>/<summary> (see skill css-styling.md #37).",
+    });
+  }
+
+  if (/\bbtn-group\b/.test(content)) {
+    findings.push({
+      gotcha: 37,
+      message:
+        "DaisyUI v4 `btn-group` was removed in v5 with no drop-in class — rebuild with `join` (`join` container + `join-item` on each button).",
+    });
+  }
+
+  if (/\bform-control\b/.test(content)) {
+    findings.push({
+      gotcha: 37,
+      message:
+        "DaisyUI v4 `form-control` was removed in v5 with no drop-in class — rebuild with `fieldset` + `label`/`legend` per DaisyUI v5's form pattern.",
+    });
+  }
+
+  return findings;
+}
+
+const MIXED_AXIS_GROUPS: Array<{ shorthand: string; sides: [string, string] }> = [
+  { shorthand: "px", sides: ["pl", "pr"] },
+  { shorthand: "mx", sides: ["ml", "mr"] },
+  { shorthand: "py", sides: ["pt", "pb"] },
+  { shorthand: "my", sides: ["mt", "mb"] },
+];
+
+/**
+ * Detect gotcha #42: an element mixing a shorthand spacing utility (`px-*`)
+ * with one of its longhand sides (`pl-*`/`pr-*`), possibly under different
+ * responsive modifiers. Tailwind v4 emits logical properties
+ * (`padding-inline` vs `padding-inline-start`), so the v3 "last one in the
+ * cascade wins" behavior no longer holds across shorthand/longhand pairs.
+ * `classes` is a single className string's already-split token list.
+ */
+export function detectLogicalPropertyConflict(classes: string[]): GotchaFinding[] {
+  const findings: GotchaFinding[] = [];
+  const utilities = classes.map((c) => c.split(":").pop() ?? c);
+
+  for (const { shorthand, sides } of MIXED_AXIS_GROUPS) {
+    const hasShorthand = utilities.some((u) => new RegExp(`^-?${shorthand}-`).test(u));
+    const hasSide = utilities.some((u) => sides.some((s) => new RegExp(`^-?${s}-`).test(u)));
+    if (hasShorthand && hasSide) {
+      findings.push({
+        gotcha: 42,
+        message:
+          `Mixed "${shorthand}-*" with "${sides[0]}-*"/"${sides[1]}-*" in the same className — ` +
+          `Tailwind v4's logical properties (padding-inline vs padding-inline-start) don't cascade the same as v3's physical properties. ` +
+          `Replace the shorthand with explicit longhand at every breakpoint (see skill css-styling.md #42).`,
+      });
+      break; // one finding per className string is enough signal
+    }
+  }
+
+  return findings;
+}