From 6ba11d35cf49c8b20fe9973be8e87dd3e554f485 Mon Sep 17 00:00:00 2001
From: Wilson WeeSheng Khoo <wilson.khooweesheng@cognizant.com>
Date: Wed, 22 Apr 2026 16:24:41 +0800
Subject: [PATCH] Update issue description for ai usage

---
 src/crawlers/commonCrawlerFunc.ts | 83 ++++++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 1 deletion(-)

diff --git a/src/crawlers/commonCrawlerFunc.ts b/src/crawlers/commonCrawlerFunc.ts
index a8f2a05d..3d797a27 100644
--- a/src/crawlers/commonCrawlerFunc.ts
+++ b/src/crawlers/commonCrawlerFunc.ts
@@ -60,6 +60,24 @@ type CustomFlowDetails = {
   pageImagePath?: any;
 };
 
+type ContrastCheckData = {
+  fgColor?: string;
+  bgColor?: string;
+  contrastRatio?: string | number;
+  fontSize?: string;
+  fontWeight?: string;
+  expectedContrastRatio?: string;
+};
+
+type ContrastExample = {
+  fgColor: string;
+  bgColor: string;
+  contrastRatio: string;
+  fontSize: string;
+  fontWeight: string;
+  expectedContrastRatio: string;
+};
+
 type FilteredResults = {
   url: string;
   pageTitle: string;
@@ -98,6 +116,65 @@ const truncateHtml = (html: string, maxBytes = 1024, suffix = '…'): string =>
   return result;
 };
 
+const formatContrastFontSize = (fontSize?: string) => {
+  if (!fontSize) return 'unknown size';
+
+  const pxMatch = fontSize.match(/\(([\d.]+px)\)/i);
+  return pxMatch ? pxMatch[1] : fontSize;
+};
+
+const buildColorContrastMessage = (node: NodeResultWithScreenshot): string | null => {
+  const checks = [...(node.any || []), ...(node.all || []), ...(node.none || [])] as Array<{
+    data?: ContrastCheckData;
+  }>;
+
+  const uniqueCombos = new Map<string, ContrastExample>();
+
+  checks.forEach(check => {
+    const data = check.data || {};
+    const hasContrastData =
+      data.fgColor ||
+      data.bgColor ||
+      data.contrastRatio !== undefined ||
+      data.expectedContrastRatio;
+
+    if (!hasContrastData) return;
+
+    const fgColor = data.fgColor || 'unknown foreground';
+    const bgColor = data.bgColor || 'unknown background';
+    const contrastRatio = String(data.contrastRatio ?? 'unknown');
+    const fontSize = formatContrastFontSize(data.fontSize);
+    const fontWeight = data.fontWeight || 'normal';
+    const expectedContrastRatio = data.expectedContrastRatio || '4.5:1';
+
+    const key = [fgColor, bgColor, fontSize, fontWeight, expectedContrastRatio].join('|');
+
+    if (!uniqueCombos.has(key)) {
+      uniqueCombos.set(key, {
+        fgColor,
+        bgColor,
+        contrastRatio,
+        fontSize,
+        fontWeight,
+        expectedContrastRatio,
+      });
+    }
+  });
+
+  if (!uniqueCombos.size) return null;
+
+  const examples = [...uniqueCombos.values()]
+    .map(
+      example =>
+        `foreground ${example.fgColor} on ${example.bgColor} at ${example.fontSize} ${example.fontWeight} text (current contrast ${example.contrastRatio}, expected ${example.expectedContrastRatio})`,
+    )
+    .join(', and ');
+
+  const targetRatio = [...uniqueCombos.values()][0]?.expectedContrastRatio || '4.5:1';
+
+  return `Multiple text elements in this component fail WCAG 1.4.3 Color Contrast Minimum. Audit all visible text in the snippet and update every failing foreground color so normal text achieves at least ${targetRatio} contrast against its actual background, with a safety margin above the minimum where possible. Known failing combinations in this snippet include ${examples}. Fix all failing text colors in the component, not just the first reported element.`;
+};
+
 export const filterAxeResults = (
   results: AxeResultsWithScreenshot,
   pageTitle: string,
@@ -145,9 +222,13 @@ export const filterAxeResults = (
           items: [],
         };
       }
-      const message = displayNeedsReview
+      const defaultMessage = displayNeedsReview
         ? failureSummary.slice(failureSummary.indexOf('\n') + 1).trim()
         : failureSummary;
+      const message =
+        rule === 'color-contrast'
+          ? buildColorContrastMessage(node) || defaultMessage
+          : defaultMessage;
 
       let finalHtml = html;
       if (html.includes('</script>')) {