@webability/core 1.0.1 → 1.1.0

package/dist/index.cjs

@@ -27086,7 +27086,7 @@ var require_axe = __commonJS({
         }
         var link_in_text_block_evaluate_default = linkInTextBlockEvaluate;
         function colorContrastEvaluate(node, options, virtualNode) {
-          var ignoreUnicode = options.ignoreUnicode, ignoreLength = options.ignoreLength, ignorePseudo = options.ignorePseudo, boldValue = options.boldValue, boldTextPt = options.boldTextPt, largeTextPt = options.largeTextPt, contrastRatio = options.contrastRatio, shadowOutlineEmMax = options.shadowOutlineEmMax, pseudoSizeThreshold = options.pseudoSizeThreshold;
+          var ignoreUnicode = options.ignoreUnicode, ignoreLength = options.ignoreLength, ignorePseudo = options.ignorePseudo, boldValue = options.boldValue, boldTextPt = options.boldTextPt, largeTextPt = options.largeTextPt, contrastRatio2 = options.contrastRatio, shadowOutlineEmMax = options.shadowOutlineEmMax, pseudoSizeThreshold = options.pseudoSizeThreshold;
           if (!_isVisibleOnScreen(node)) {
             this.data({
               messageKey: "hidden"
@@ -27106,7 +27106,7 @@ var require_axe = __commonJS({
           var bold = parseFloat(fontWeight) >= boldValue || fontWeight === "bold";
           var ptSize = Math.ceil(fontSize * 72) / 96;
           var isSmallFont = bold && ptSize < boldTextPt || !bold && ptSize < largeTextPt;
-          var _ref134 = isSmallFont ? contrastRatio.normal : contrastRatio.large, expected = _ref134.expected, minThreshold = _ref134.minThreshold, maxThreshold = _ref134.maxThreshold;
+          var _ref134 = isSmallFont ? contrastRatio2.normal : contrastRatio2.large, expected = _ref134.expected, minThreshold = _ref134.minThreshold, maxThreshold = _ref134.maxThreshold;
           var pseudoElm = findPseudoElement(virtualNode, {
             ignorePseudo,
             pseudoSizeThreshold
@@ -34065,16 +34065,145 @@ var init_modal_dismissal = __esm({
   }
 });
 
+// src/engines/htmlcs.ts
+var htmlcs_exports = {};
+__export(htmlcs_exports, {
+  runHtmlcs: () => runHtmlcs
+});
+async function runHtmlcs(page, standard = "WCAG2AA") {
+  try {
+    await page.addScriptTag({ content: `
+      window.__htmlcsLoaded = false;
+      window.__htmlcsResults = [];
+    ` });
+    const p = page;
+    if (p.addScriptTag) {
+      await p.addScriptTag({ url: HTMLCS_CDN }).catch(() => {
+      });
+    }
+    await new Promise((r) => setTimeout(r, 1e3));
+    const results = await page.evaluate((std) => {
+      return new Promise((resolve) => {
+        const w = window;
+        if (!w.HTMLCS) {
+          resolve([]);
+          return;
+        }
+        w.HTMLCS.process(std, document, () => {
+          const messages = w.HTMLCS.getMessages();
+          const issues = messages.filter((m) => m.type === 1).slice(0, 50).map((m) => {
+            let selector = "";
+            try {
+              if (m.element && m.element.tagName) {
+                const el = m.element;
+                selector = el.id ? `#${el.id}` : el.className ? `${el.tagName.toLowerCase()}.${el.className.split(" ")[0]}` : el.tagName.toLowerCase();
+              }
+            } catch {
+            }
+            return {
+              type: m.type,
+              code: m.code || "",
+              msg: m.msg || "",
+              element: m.element?.outerHTML?.slice(0, 150) || "",
+              selector
+            };
+          });
+          resolve(issues);
+        });
+      });
+    }, standard);
+    return results.map((r, i) => {
+      const wcag = extractWcagFromCode(r.code);
+      return {
+        id: `htmlcs-${i}-${hashStr(r.selector)}`,
+        source: "webability",
+        // don't expose engine name
+        type: r.code.split(".").pop() || r.code,
+        wcag,
+        level: "AA",
+        impact: "moderate",
+        message: r.msg.slice(0, 200),
+        selector: r.selector,
+        html: r.element
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+function extractWcagFromCode(code) {
+  const match = code.match(/Guideline(\d+)_(\d+)\.(\d+)_(\d+)_(\d+)/);
+  if (match) return `${match[3]}.${match[4]}.${match[5]}`;
+  const simple = code.match(/(\d+)_(\d+)_(\d+)/);
+  if (simple) return `${simple[1]}.${simple[2]}.${simple[3]}`;
+  return "";
+}
+function hashStr(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (h << 5) - h + s.charCodeAt(i) | 0;
+  return Math.abs(h).toString(36);
+}
+var HTMLCS_CDN;
+var init_htmlcs = __esm({
+  "src/engines/htmlcs.ts"() {
+    "use strict";
+    HTMLCS_CDN = "https://squizlabs.github.io/HTML_CodeSniffer/build/HTMLCS.js";
+  }
+});
+
+// src/engines/dedup.ts
+var dedup_exports = {};
+__export(dedup_exports, {
+  deduplicateIssues: () => deduplicateIssues2
+});
+function deduplicateIssues2(allIssues) {
+  const seen = /* @__PURE__ */ new Map();
+  const sorted = [...allIssues].sort((a, b) => {
+    const sourceOrder = { webability: 0, "axe-core": 1, "deep-analysis": 2 };
+    const aOrder = sourceOrder[a.source] ?? 3;
+    const bOrder = sourceOrder[b.source] ?? 3;
+    return aOrder - bOrder;
+  });
+  for (const issue of sorted) {
+    const key = normalizeKey(issue);
+    if (!seen.has(key)) {
+      seen.set(key, issue);
+    } else {
+      const existing = seen.get(key);
+      if (!existing.fix?.suggestedValue && issue.fix?.suggestedValue) {
+        seen.set(key, issue);
+      }
+    }
+  }
+  return Array.from(seen.values());
+}
+function normalizeKey(issue) {
+  const sel = issue.selector.replace(/:focus-visible$/, "").replace(/:focus$/, "").replace(/\[data-[^\]]+\]/g, "").trim();
+  const wcag = issue.wcag || "";
+  if (sel && wcag) return `${sel}::${wcag}`;
+  return `${issue.type}::${sel || issue.id}`;
+}
+var init_dedup = __esm({
+  "src/engines/dedup.ts"() {
+    "use strict";
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
   VIEWPORT_SIZES: () => VIEWPORT_SIZES,
   WCAG_BY_ISSUE: () => WCAG_BY_ISSUE,
+  detectFramework: () => detectFramework,
   dismissModals: () => dismissModals,
   extractSiteTheme: () => extractSiteTheme,
+  generateDevSuggestion: () => generateDevSuggestion,
+  getContrastRatio: () => getContrastRatio,
   runAxe: () => runAxe,
   runDetectors: () => runDetectors,
   scan: () => scan,
+  solveContrast: () => solveContrast,
+  suggestTailwindFix: () => suggestTailwindFix,
   toHtmlReport: () => toHtmlReport
 });
 module.exports = __toCommonJS(index_exports);
@@ -39899,15 +40028,15 @@ async function scan(target, options) {
     url = page.url();
   }
   try {
-    const issues = [];
+    const allIssues = [];
     const detected = await runDetectors(page);
-    issues.push(...detected.map(detectedToScanIssue));
+    allIssues.push(...detected.map(detectedToScanIssue));
     if (opts.includeAxe) {
       try {
         const axeResults = await runAxe(page, opts.wcagTags ?? DEFAULT_WCAG_TAGS);
         for (const v of axeResults.violations) {
           for (const node of v.nodes) {
-            issues.push({
+            allIssues.push({
               id: `axe-${v.id}-${hashSelector(node.target?.[0] ?? "")}`,
               source: "axe-core",
               type: v.id,
@@ -39923,6 +40052,14 @@ async function scan(target, options) {
       } catch {
       }
     }
+    try {
+      const { runHtmlcs: runHtmlcs2 } = await Promise.resolve().then(() => (init_htmlcs(), htmlcs_exports));
+      const htmlcsIssues = await runHtmlcs2(page);
+      allIssues.push(...htmlcsIssues);
+    } catch {
+    }
+    const { deduplicateIssues: dedup } = await Promise.resolve().then(() => (init_dedup(), dedup_exports));
+    const issues = dedup(allIssues);
     if (opts.deep && opts.deepApiKey) {
       try {
         const deepIssues = await runDeepViaApi(url, issues, opts);
@@ -40086,15 +40223,439 @@ function toHtmlReport(result) {
 function esc(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+
+// src/suggestions/frameworkDetector.ts
+async function detectFramework(page) {
+  return page.evaluate(() => {
+    const html = document.documentElement.outerHTML;
+    const classes = Array.from(document.querySelectorAll("[class]")).slice(0, 200).map((el) => el.className).join(" ");
+    const twPatterns = /\b(text-(?:gray|slate|zinc|neutral|stone|red|orange|amber|yellow|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-\d{2,3}|bg-(?:gray|slate|blue|red|green)-\d{2,3}|flex|grid|p-\d|m-\d|rounded|shadow|border-\[|text-\[|w-\d|h-\d)\b/g;
+    const twMatches = classes.match(twPatterns) || [];
+    const twScore = Math.min(twMatches.length / 10, 1);
+    const bsPatterns = /\b(btn-(?:primary|secondary|danger|warning|success)|col-(?:sm|md|lg|xl)-\d|container-fluid|navbar-(?:expand|collapse)|form-control|card-body|modal-dialog)\b/g;
+    const bsMatches = classes.match(bsPatterns) || [];
+    const bsScore = Math.min(bsMatches.length / 5, 1);
+    const muiPatterns = /\b(Mui[A-Z]|MuiButton|MuiTypography|MuiPaper|css-[a-z0-9]{5,}|makeStyles)\b/g;
+    const muiMatches = (classes + " " + html.slice(0, 5e3)).match(muiPatterns) || [];
+    const muiScore = Math.min(muiMatches.length / 5, 1);
+    const hasTwConfig = !!document.querySelector("style[data-tw]") || html.includes("tailwindcss") || classes.includes("antialiased");
+    if (twScore > 0.3 || hasTwConfig) {
+      const styles = document.documentElement.style.cssText || "";
+      const isV4 = styles.includes("oklch") || !!document.querySelector('[class*="text-[oklch"]');
+      return { framework: "tailwind", version: isV4 ? "4" : "3", confidence: Math.max(twScore, hasTwConfig ? 0.8 : 0) };
+    }
+    if (bsScore > 0.3) return { framework: "bootstrap", confidence: bsScore };
+    if (muiScore > 0.3) return { framework: "mui", confidence: muiScore };
+    return { framework: "plain-css", confidence: 0.5 };
+  });
+}
+
+// src/suggestions/contrastSolver.ts
+function hexToRgb(hex) {
+  hex = hex.replace("#", "");
+  if (hex.length === 3) hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  const n = parseInt(hex, 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function rgbToHex(r, g, b) {
+  return "#" + [r, g, b].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("");
+}
+function srgbToLinear(c) {
+  const s = c / 255;
+  return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+}
+function relativeLuminance(r, g, b) {
+  return 0.2126 * srgbToLinear(r) + 0.7152 * srgbToLinear(g) + 0.0722 * srgbToLinear(b);
+}
+function contrastRatio(l1, l2) {
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function parseColor(color) {
+  if (color.startsWith("#")) return hexToRgb(color);
+  const rgbMatch = color.match(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/);
+  if (rgbMatch) return [parseInt(rgbMatch[1]), parseInt(rgbMatch[2]), parseInt(rgbMatch[3])];
+  return null;
+}
+function getContrastRatio(fg, bg) {
+  const fgRgb = parseColor(fg);
+  const bgRgb = parseColor(bg);
+  if (!fgRgb || !bgRgb) return 0;
+  return contrastRatio(relativeLuminance(...fgRgb), relativeLuminance(...bgRgb));
+}
+function solveContrast(fgHex, bgHex, requiredRatio = 4.5) {
+  const fg = parseColor(fgHex);
+  const bg = parseColor(bgHex);
+  if (!fg || !bg) return null;
+  const bgLum = relativeLuminance(...bg);
+  const currentRatio = contrastRatio(relativeLuminance(...fg), bgLum);
+  if (currentRatio >= requiredRatio) return null;
+  const fgLum = relativeLuminance(...fg);
+  const needDarker = fgLum > bgLum;
+  let lo = 0, hi = 1;
+  let bestColor = fg;
+  for (let i = 0; i < 20; i++) {
+    const mid = (lo + hi) / 2;
+    const shifted = needDarker ? [fg[0] * (1 - mid), fg[1] * (1 - mid), fg[2] * (1 - mid)] : [fg[0] + (255 - fg[0]) * mid, fg[1] + (255 - fg[1]) * mid, fg[2] + (255 - fg[2]) * mid];
+    const shiftedLum = relativeLuminance(shifted[0], shifted[1], shifted[2]);
+    const ratio = contrastRatio(shiftedLum, bgLum);
+    if (ratio >= requiredRatio) {
+      bestColor = shifted;
+      hi = mid;
+    } else {
+      lo = mid;
+    }
+  }
+  const suggestedHex = rgbToHex(bestColor[0], bestColor[1], bestColor[2]);
+  const suggestedRatio = getContrastRatio(suggestedHex, bgHex);
+  return {
+    currentColor: fgHex,
+    suggestedColor: suggestedHex,
+    currentRatio: Math.round(currentRatio * 100) / 100,
+    suggestedRatio: Math.round(suggestedRatio * 100) / 100,
+    requiredRatio,
+    bgColor: bgHex
+  };
+}
+
+// src/suggestions/tailwindMapper.ts
+var TW_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" },
+  red: { "50": "#fef2f2", "100": "#fee2e2", "200": "#fecaca", "300": "#fca5a5", "400": "#f87171", "500": "#ef4444", "600": "#dc2626", "700": "#b91c1c", "800": "#991b1b", "900": "#7f1d1d", "950": "#450a0a" },
+  blue: { "50": "#eff6ff", "100": "#dbeafe", "200": "#bfdbfe", "300": "#93c5fd", "400": "#60a5fa", "500": "#3b82f6", "600": "#2563eb", "700": "#1d4ed8", "800": "#1e40af", "900": "#1e3a8a", "950": "#172554" },
+  green: { "50": "#f0fdf4", "100": "#dcfce7", "200": "#bbf7d0", "300": "#86efac", "400": "#4ade80", "500": "#22c55e", "600": "#16a34a", "700": "#15803d", "800": "#166534", "900": "#14532d", "950": "#052e16" },
+  indigo: { "50": "#eef2ff", "100": "#e0e7ff", "200": "#c7d2fe", "300": "#a5b4fc", "400": "#818cf8", "500": "#6366f1", "600": "#4f46e5", "700": "#4338ca", "800": "#3730a3", "900": "#312e81", "950": "#1e1b4e" },
+  purple: { "50": "#faf5ff", "100": "#f3e8ff", "200": "#e9d5ff", "300": "#d8b4fe", "400": "#c084fc", "500": "#a855f7", "600": "#9333ea", "700": "#7e22ce", "800": "#6b21a8", "900": "#581c87", "950": "#3b0764" },
+  amber: { "50": "#fffbeb", "100": "#fef3c7", "200": "#fde68a", "300": "#fcd34d", "400": "#fbbf24", "500": "#f59e0b", "600": "#d97706", "700": "#b45309", "800": "#92400e", "900": "#78350f", "950": "#451a03" }
+};
+function hexDistance(a, b) {
+  const ar = parseColor(a);
+  const br = parseColor(b);
+  if (!ar || !br) return Infinity;
+  return Math.sqrt((ar[0] - br[0]) ** 2 + (ar[1] - br[1]) ** 2 + (ar[2] - br[2]) ** 2);
+}
+function hexToTailwindClass(hex, prefix = "text") {
+  let bestMatch = null;
+  let bestDist = Infinity;
+  for (const [colorName, shades] of Object.entries(TW_COLORS)) {
+    for (const [shade, shadeHex] of Object.entries(shades)) {
+      const dist = hexDistance(hex.toLowerCase(), shadeHex);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestMatch = `${prefix}-${colorName}-${shade}`;
+      }
+    }
+  }
+  return bestDist < 30 ? bestMatch : null;
+}
+function suggestTailwindFix(fgHex, bgHex, requiredRatio = 4.5, prefix = "text") {
+  const currentClass = hexToTailwindClass(fgHex, prefix);
+  const currentRatio = getContrastRatio(fgHex, bgHex);
+  if (currentRatio >= requiredRatio) return null;
+  let bestFamily = "gray";
+  let bestShade = "500";
+  let bestDist = Infinity;
+  for (const [colorName, shades2] of Object.entries(TW_COLORS)) {
+    for (const [shade, shadeHex] of Object.entries(shades2)) {
+      const dist = hexDistance(fgHex.toLowerCase(), shadeHex);
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestFamily = colorName;
+        bestShade = shade;
+      }
+    }
+  }
+  const shades = Object.entries(TW_COLORS[bestFamily] || TW_COLORS.gray);
+  const bgRgb = parseColor(bgHex);
+  if (!bgRgb) return null;
+  const bgIsLight = (bgRgb[0] + bgRgb[1] + bgRgb[2]) / 3 > 128;
+  const orderedShades = bgIsLight ? shades.sort((a, b) => parseInt(b[0]) - parseInt(a[0])) : shades.sort((a, b) => parseInt(a[0]) - parseInt(b[0]));
+  for (const [shade, shadeHex] of orderedShades) {
+    const ratio = getContrastRatio(shadeHex, bgHex);
+    if (ratio >= requiredRatio) {
+      return {
+        currentClass,
+        suggestedClass: `${prefix}-${bestFamily}-${shade}`,
+        currentHex: fgHex,
+        suggestedHex: shadeHex,
+        currentRatio: Math.round(currentRatio * 100) / 100,
+        suggestedRatio: Math.round(ratio * 100) / 100,
+        requiredRatio
+      };
+    }
+  }
+  const solved = solveContrast(fgHex, bgHex, requiredRatio);
+  if (solved) {
+    return {
+      currentClass,
+      suggestedClass: hexToTailwindClass(solved.suggestedColor, prefix) || `${prefix}-[${solved.suggestedColor}]`,
+      currentHex: fgHex,
+      suggestedHex: solved.suggestedColor,
+      currentRatio: solved.currentRatio,
+      suggestedRatio: solved.suggestedRatio,
+      requiredRatio
+    };
+  }
+  return null;
+}
+
+// src/suggestions/devSuggestions.ts
+function generateDevSuggestion(issue, framework, elementClasses, fgColor, bgColor) {
+  const wcagLink = `https://www.w3.org/WAI/WCAG21/Understanding/${issue.wcag.replace(/\./g, "")}`;
+  if (issue.type === "contrast_insufficient" || issue.type === "color-contrast") {
+    return generateContrastSuggestion(issue, framework, elementClasses, fgColor, bgColor, wcagLink);
+  }
+  if (issue.type === "non_text_contrast_insufficient") {
+    return generateNonTextContrastSuggestion(issue, framework, elementClasses, wcagLink);
+  }
+  if (issue.type === "focus_not_visible") {
+    return generateFocusSuggestion(issue, framework, wcagLink);
+  }
+  if (issue.type === "missing_alt") {
+    return {
+      issue,
+      problem: "Image has no alt text \u2014 screen readers skip it entirely.",
+      fix: framework === "tailwind" ? 'Add alt="description" to the <img>. For decorative images, use alt="" (empty).' : 'Add alt="description" to the <img>. For decorative images, use alt="" and role="presentation".',
+      wcagLink
+    };
+  }
+  if (issue.type === "target_too_small") {
+    const size = issue.fix?.currentValue || "unknown";
+    return {
+      issue,
+      problem: `Touch target is ${size} \u2014 minimum 24x24px required (WCAG 2.5.8).`,
+      fix: framework === "tailwind" ? "Add min-h-[44px] min-w-[44px] p-2 to the element for comfortable tap targets." : "Add min-height: 44px; min-width: 44px; padding: 8px; to the element.",
+      before: framework === "tailwind" && elementClasses ? elementClasses : void 0,
+      after: framework === "tailwind" && elementClasses ? elementClasses + " min-h-[44px] min-w-[44px]" : void 0,
+      wcagLink
+    };
+  }
+  if (issue.type === "decorative_icon") {
+    return {
+      issue,
+      problem: "SVG/icon is announced by screen readers but has no meaningful content.",
+      fix: `Add aria-hidden="true" to the SVG element \u2014 it's decorative.`,
+      before: "<svg ...",
+      after: '<svg aria-hidden="true" ...',
+      wcagLink
+    };
+  }
+  if (issue.type === "heading_skip") {
+    return {
+      issue,
+      problem: `Heading hierarchy skips a level \u2014 confuses screen reader navigation.`,
+      fix: "Use sequential heading levels (h1 \u2192 h2 \u2192 h3). Don't skip from h2 to h4.",
+      wcagLink
+    };
+  }
+  if (issue.type === "missing_label") {
+    return {
+      issue,
+      problem: "Form input has no label \u2014 screen readers can't identify what to enter.",
+      fix: framework === "tailwind" ? 'Add a <label htmlFor="id"> or aria-label="description" to the input.' : 'Add a <label for="id"> element or aria-label attribute.',
+      wcagLink
+    };
+  }
+  if (issue.type === "skip_link") {
+    return {
+      issue,
+      problem: "Page has no skip navigation link \u2014 keyboard users must tab through the entire header on every page.",
+      fix: 'Add a visually-hidden skip link as the first focusable element: <a href="#main-content" class="sr-only focus:not-sr-only">Skip to content</a>',
+      wcagLink
+    };
+  }
+  if (issue.type === "motion_without_reduced_motion") {
+    return {
+      issue,
+      problem: 'Page has animations but no @media (prefers-reduced-motion) query. Users who set "Reduce motion" in OS settings still see all animations.',
+      fix: framework === "tailwind" ? "Use Tailwind's motion-safe: and motion-reduce: variants, or add @media (prefers-reduced-motion: reduce) to globals.css." : "Add @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }",
+      wcagLink
+    };
+  }
+  if (issue.type === "weak_link_name" || issue.type === "weak_button_name") {
+    const name = issue.fix?.currentValue || "";
+    return {
+      issue,
+      problem: `"${name}" is too generic \u2014 screen reader users can't tell what this links to.`,
+      fix: `Add descriptive text or aria-label. E.g., "${name} about accessibility testing" instead of just "${name}".`,
+      wcagLink
+    };
+  }
+  if (issue.type === "svg_missing_name") {
+    return {
+      issue,
+      problem: 'SVG has no accessible name \u2014 screen readers announce it as "image" with no description.',
+      fix: 'If decorative: add aria-hidden="true". If meaningful: add aria-label="description" or <title> inside the SVG.',
+      before: "<svg ...",
+      after: '<svg aria-hidden="true" ...   (decorative)\n    <svg aria-label="Search icon" ...   (meaningful)',
+      wcagLink
+    };
+  }
+  if (issue.type === "new_window_link") {
+    return {
+      issue,
+      problem: "Link opens in a new tab without warning \u2014 disorienting for screen reader users.",
+      fix: 'Add "(opens in new tab)" to the link text or aria-label.',
+      wcagLink
+    };
+  }
+  if (issue.type === "missing_required_indicator") {
+    return {
+      issue,
+      problem: "Required form field has no visual indicator \u2014 users don't know it's mandatory.",
+      fix: 'Add aria-required="true" and a visual asterisk (*) to the label.',
+      wcagLink
+    };
+  }
+  if (issue.type === "redundant_role") {
+    return {
+      issue,
+      problem: "Element has a redundant ARIA role matching its implicit HTML role.",
+      fix: 'Remove the role attribute \u2014 <nav> already implies role="navigation".',
+      wcagLink
+    };
+  }
+  if (issue.type === "duplicate_id") {
+    return {
+      issue,
+      problem: "Multiple elements share the same ID \u2014 breaks label associations and ARIA references.",
+      fix: "Make each id unique across the page.",
+      wcagLink
+    };
+  }
+  if (issue.type === "insufficient_navigation") {
+    return {
+      issue,
+      problem: "Page has only one way to navigate \u2014 WCAG requires multiple (e.g., nav + search, or nav + sitemap).",
+      fix: "Add a search input, sitemap link, or breadcrumbs alongside the main navigation.",
+      wcagLink
+    };
+  }
+  if (issue.type === "image_of_text") {
+    return {
+      issue,
+      problem: "Image appears to contain text \u2014 text in images can't be resized, translated, or read by screen readers.",
+      fix: "Replace the image with real text styled with CSS. Exception: logos are exempt.",
+      wcagLink
+    };
+  }
+  if (issue.type === "focus_obscured_by_sticky") {
+    return {
+      issue,
+      problem: "Sticky header may obscure focused elements when tabbing \u2014 users can't see where focus is.",
+      fix: framework === "tailwind" ? "Add scroll-pt-20 to the html element, or scroll-padding-top: 80px to account for the sticky header height." : "Add scroll-padding-top: 80px to html { } in your CSS.",
+      wcagLink
+    };
+  }
+  if (issue.type === "missing_media_controls") {
+    return {
+      issue,
+      problem: "Video/audio element has no visible controls \u2014 users can't pause, stop, or adjust volume.",
+      fix: "Add the controls attribute to <video> or <audio>, or implement custom accessible controls with proper ARIA.",
+      wcagLink
+    };
+  }
+  if (issue.type === "multiple_h1") {
+    return {
+      issue,
+      problem: "Page has multiple <h1> elements \u2014 should have exactly one.",
+      fix: "Keep one <h1> for the main page title. Change others to <h2>.",
+      wcagLink
+    };
+  }
+  return {
+    issue,
+    problem: issue.message.replace(/: set .*/, "").replace(/: missing .*/, " is missing"),
+    fix: issue.fix?.suggestedValue && !issue.fix.suggestedValue.includes("!important") ? `Set ${issue.fix.attribute}="${issue.fix.suggestedValue.slice(0, 60)}"` : `Review this element for WCAG ${issue.wcag} compliance.`,
+    wcagLink
+  };
+}
+function generateContrastSuggestion(issue, framework, elementClasses, fgColor, bgColor, wcagLink = "") {
+  const fg = fgColor || issue.fix?.currentValue || "";
+  const bg = bgColor || "#ffffff";
+  const currentRatio = fg && bg ? getContrastRatio(fg, bg) : 0;
+  const requiredRatio = 4.5;
+  if (framework === "tailwind" && fg && bg) {
+    const twSuggestion = suggestTailwindFix(fg, bg, requiredRatio);
+    if (twSuggestion) {
+      return {
+        issue,
+        problem: `Contrast ratio ${twSuggestion.currentRatio}:1 \u2014 needs ${requiredRatio}:1 for WCAG AA.`,
+        fix: twSuggestion.currentClass ? `Change ${twSuggestion.currentClass} \u2192 ${twSuggestion.suggestedClass}` : `Use ${twSuggestion.suggestedClass} (${twSuggestion.suggestedHex})`,
+        before: twSuggestion.currentClass || void 0,
+        after: twSuggestion.suggestedClass,
+        contrast: {
+          current: twSuggestion.currentRatio,
+          required: requiredRatio,
+          suggested: twSuggestion.suggestedRatio,
+          fgColor: fg,
+          bgColor: bg,
+          suggestedColor: twSuggestion.suggestedHex
+        },
+        wcagLink
+      };
+    }
+  }
+  const solved = fg && bg ? solveContrast(fg, bg, requiredRatio) : null;
+  if (solved) {
+    return {
+      issue,
+      problem: `Contrast ratio ${solved.currentRatio}:1 \u2014 needs ${requiredRatio}:1 for WCAG AA.`,
+      fix: `Change color from ${solved.currentColor} to ${solved.suggestedColor}`,
+      contrast: {
+        current: solved.currentRatio,
+        required: requiredRatio,
+        suggested: solved.suggestedRatio,
+        fgColor: fg,
+        bgColor: bg,
+        suggestedColor: solved.suggestedColor
+      },
+      wcagLink
+    };
+  }
+  return {
+    issue,
+    problem: "Text contrast is below WCAG AA minimum.",
+    fix: "Darken the text color or lighten the background to achieve at least 4.5:1 contrast ratio.",
+    wcagLink
+  };
+}
+function generateNonTextContrastSuggestion(issue, framework, elementClasses, wcagLink = "") {
+  return {
+    issue,
+    problem: "Non-text element (border, icon, UI component) has contrast below 3:1 against its background.",
+    fix: framework === "tailwind" ? "Use a darker border color \u2014 e.g., border-gray-400 instead of border-gray-200. Non-text elements need 3:1 contrast." : "Darken the border/outline color to achieve at least 3:1 contrast against the background.",
+    wcagLink
+  };
+}
+function generateFocusSuggestion(issue, framework, wcagLink = "") {
+  return {
+    issue,
+    problem: "Element has no visible focus indicator \u2014 keyboard users can't see where they are.",
+    fix: framework === "tailwind" ? "Add focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2 to the element." : "Add :focus-visible { outline: 2px solid #2563eb; outline-offset: 2px; } to the element's CSS.",
+    before: framework === "tailwind" ? 'className="..."' : void 0,
+    after: framework === "tailwind" ? 'className="... focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"' : void 0,
+    wcagLink
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   VIEWPORT_SIZES,
   WCAG_BY_ISSUE,
+  detectFramework,
   dismissModals,
   extractSiteTheme,
+  generateDevSuggestion,
+  getContrastRatio,
   runAxe,
   runDetectors,
   scan,
+  solveContrast,
+  suggestTailwindFix,
   toHtmlReport
 });
 /*! Bundled license information: