High Contrast Color Combinations

How It Works

High-contrast token system with automatic ratio validation (TypeScript + CSS)

/* ═══════════════════════════════════════════════════════
   High Contrast Color Token System
   Auto-validates every pair meets minimum WCAG ratio
   Drop into any design system or Tailwind config
   ═══════════════════════════════════════════════════════ */

interface ContrastPair {
  name: string;
  fg: string;
  bg: string;
  minRatio: number; // 4.5 for text, 3 for UI
  usage: string;
}

const highContrastTokens: ContrastPair[] = [
  // Light mode text
  { name: "text-primary", fg: "#1a1a2e", bg: "#ffffff", minRatio: 7, usage: "Body copy" },
  { name: "text-secondary", fg: "#374151", bg: "#ffffff", minRatio: 4.5, usage: "Captions, labels" },
  { name: "text-on-brand", fg: "#ffffff", bg: "#1d4ed8", minRatio: 4.5, usage: "Button labels" },
  // Dark mode text
  { name: "dark-text-primary", fg: "#f1f5f9", bg: "#0f172a", minRatio: 7, usage: "Dark body" },
  { name: "dark-text-secondary", fg: "#cbd5e1", bg: "#1e293b", minRatio: 4.5, usage: "Dark captions" },
  // UI components
  { name: "border-input", fg: "#6b7280", bg: "#f9fafb", minRatio: 3, usage: "Form borders" },
  { name: "icon-default", fg: "#374151", bg: "#ffffff", minRatio: 3, usage: "Icons" },
  { name: "focus-ring", fg: "#1d4ed8", bg: "#ffffff", minRatio: 3, usage: "Focus indicator" },
  // Status colors
  { name: "badge-error", fg: "#991b1b", bg: "#fee2e2", minRatio: 4.5, usage: "Error badge text" },
  { name: "badge-success", fg: "#166534", bg: "#dcfce7", minRatio: 4.5, usage: "Success badge" },
];

// Luminance calculation (WCAG 2.x relative luminance)
function hexToRgb(hex: string): [number, number, number] {
  const h = hex.replace("#", "");
  return [parseInt(h.slice(0,2),16), parseInt(h.slice(2,4),16), parseInt(h.slice(4,6),16)];
}

function relativeLuminance(hex: string): number {
  const [r, g, b] = hexToRgb(hex).map(c => {
    const s = c / 255;
    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

function contrastRatio(fg: string, bg: string): number {
  const l1 = relativeLuminance(fg);
  const l2 = relativeLuminance(bg);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);
  return (lighter + 0.05) / (darker + 0.05);
}

// Validate all tokens
function auditTokens(tokens: ContrastPair[]): { pass: ContrastPair[]; fail: ContrastPair[] } {
  const pass: ContrastPair[] = [];
  const fail: ContrastPair[] = [];
  
  for (const token of tokens) {
    const ratio = contrastRatio(token.fg, token.bg);
    if (ratio >= token.minRatio) {
      pass.push(token);
    } else {
      fail.push(token);
      console.warn(
        `❌ FAIL: ${token.name} — ratio ${ratio.toFixed(2)} < required ${token.minRatio}`
      );
    }
  }
  
  console.log(`✅ ${pass.length}/${tokens.length} tokens pass | ❌ ${fail.length} failures`);
  return { pass, fail };
}

// Generate CSS custom properties from validated tokens
function toCssVariables(tokens: ContrastPair[]): string {
  return tokens.map(t =>
    `  --${t.name}-fg: ${t.fg};
  --${t.name}-bg: ${t.bg}; /* ratio: ${contrastRatio(t.fg, t.bg).toFixed(1)}:1, min: ${t.minRatio}:1 */`
  ).join("
");
}

// Run audit
const { pass, fail } = auditTokens(highContrastTokens);
console.log("
:root {
" + toCssVariables(pass) + "
}");
if (fail.length) console.error("Fix these tokens before shipping:", fail.map(f => f.name));

Copy and paste into your project — free to use.

Pro Tips

• ▸
  Never trust a contrast ratio from a design tool without testing on the actual coded surface. Figma and Sketch measure against the artboard, not the real layered background your element will render on.
• ▸
  Build a contrast matrix: list all text tokens in rows, all surface tokens in columns, and fill each cell with the measured ratio. Any cell below 4.5:1 for text or 3:1 for UI is a failure. This one artifact catches 80% of issues before they ship.
• ▸
  For brands that demand saturated accent colors: use them for large text (3:1 threshold) or non-text elements, never for body copy. Reserve body text for the near-black/near-white tokens that guarantee 7:1+.
• ▸
  Dark mode is not inverted light mode. Build separate pairs. Light text on dark needs 15-20% less lightness difference than dark text on light to appear equally legible (due to halation). Start dark-mode body text at OKLCH L=90, not L=100.
• ▸
  Test outdoor readability: take your phone outside on a sunny day. If you squint at any text, the contrast is too low regardless of what the number says. WCAG ratios assume indoor viewing.
• ▸
  Windows High Contrast Mode overrides your colors entirely. Test that your layout still makes sense when the system imposes its own high-contrast palette. This catches issues where you rely on color alone for structure.
• ▸
  Focus ring formula that always works: 2px solid with 2px offset, using a color that achieves 3:1 against both the focused element's background AND the page surface behind the offset gap.
• ▸
  For chart colors: ensure 3:1 between adjacent series, not just against the background. Two similar blues next to each other fail even if both individually pass against white.
• ▸
  Pre-ship checklist: (1) All body text 7:1+ on actual surfaces (2) Large text and headings 4.5:1+ (3) UI borders/icons 3:1+ against adjacent colors (4) Focus rings 3:1+ in both directions (5) Chart series 3:1+ between neighbors (6) Button labels pass in ALL states (7) Dark mode tested independently (8) One outdoor device check (9) Windows High Contrast verified (10) Ratio documented in design tokens.