fix: use MUI-style contrast threshold to handle saturated background colors

The previous approach compared WCAG contrast ratios of textPrimary vs
textReverse, which produced wrong results on saturated colors like red
where both ratios are near-tied. Switch to a threshold-based approach:
if the lighter text candidate meets WCAG AA large-text contrast (3.0),
use it; otherwise fall back to the darker candidate.

Author: hervedombya

src/lib/utils.test.ts

@@ -4,22 +4,28 @@ const LIGHT_TEXT = '#EAEAEA';
 const DARK_TEXT = '#000000';
 
 describe('getContrastText', () => {
-  it('returns textPrimary on dark backgrounds when textPrimary is light', () => {
+  it('returns light text on dark backgrounds', () => {
     expect(getContrastText('#000000', LIGHT_TEXT, DARK_TEXT)).toBe(LIGHT_TEXT);
     expect(getContrastText('#1A1A1A', LIGHT_TEXT, DARK_TEXT)).toBe(LIGHT_TEXT);
     expect(getContrastText('#121219', LIGHT_TEXT, DARK_TEXT)).toBe(LIGHT_TEXT);
     expect(getContrastText('#2F4185', LIGHT_TEXT, DARK_TEXT)).toBe(LIGHT_TEXT);
   });
 
-  it('returns textReverse on light backgrounds when textPrimary is light', () => {
+  it('returns dark text on light backgrounds', () => {
     expect(getContrastText('#FFFFFF', LIGHT_TEXT, DARK_TEXT)).toBe(DARK_TEXT);
     expect(getContrastText('#F5F5F5', LIGHT_TEXT, DARK_TEXT)).toBe(DARK_TEXT);
     expect(getContrastText('#FCFCFC', LIGHT_TEXT, DARK_TEXT)).toBe(DARK_TEXT);
   });
 
-  it('picks the text color with better contrast against a vivid background', () => {
-    expect(getContrastText('#E9041E', LIGHT_TEXT, DARK_TEXT)).toBe(DARK_TEXT);
-    expect(getContrastText('#E9041E', '#FFFFFF', '#000000')).toBe('#FFFFFF');
+  it('returns light text on saturated colors where WCAG luminance is ambiguous', () => {
+    expect(getContrastText('#E60028', LIGHT_TEXT, DARK_TEXT)).toBe(LIGHT_TEXT);
+    expect(getContrastText('#E9041E', LIGHT_TEXT, DARK_TEXT)).toBe(LIGHT_TEXT);
+    expect(getContrastText('#E60028', '#0D0D0D', '#EAEAEA')).toBe('#EAEAEA');
+  });
+
+  it('works regardless of which token is lighter', () => {
+    expect(getContrastText('#000000', DARK_TEXT, LIGHT_TEXT)).toBe(LIGHT_TEXT);
+    expect(getContrastText('#FFFFFF', DARK_TEXT, LIGHT_TEXT)).toBe(DARK_TEXT);
   });
 
   it('handles 3-character hex shorthand', () => {

src/lib/utils.ts

@@ -62,16 +62,26 @@ const luminanceOf = (hex: string): number => {
   return relativeLuminance(r, g, b);
 };
 
+// Minimum WCAG contrast ratio to consider a text color readable on a background.
+// 3.0 corresponds to WCAG AA for large text — same threshold used by MUI.
+const CONTRAST_THRESHOLD = 3;
+
 export const getContrastText = (
   bgColor: string,
   textPrimary: string,
   textReverse: string,
 ): string | null => {
   try {
     const bgLum = luminanceOf(bgColor);
-    const primaryContrast = wcagContrastRatio(luminanceOf(textPrimary), bgLum);
-    const reverseContrast = wcagContrastRatio(luminanceOf(textReverse), bgLum);
-    return reverseContrast > primaryContrast ? textReverse : textPrimary;
+    const primaryLum = luminanceOf(textPrimary);
+    const reverseLum = luminanceOf(textReverse);
+
+    const lighterText = primaryLum >= reverseLum ? textPrimary : textReverse;
+    const darkerText = primaryLum >= reverseLum ? textReverse : textPrimary;
+
+    const lighterContrast = wcagContrastRatio(primaryLum >= reverseLum ? primaryLum : reverseLum, bgLum);
+
+    return lighterContrast >= CONTRAST_THRESHOLD ? lighterText : darkerText;
   } catch {
     return null;
   }