eliferjunior/contrast-check

Contrast Check

Overview

Check color pairs against WCAG 2.1 contrast requirements. Pass in hex colors and get contrast ratios with AA/AAA pass/fail results for both normal and large text.

• Checking if a text color is readable against a background color
• Auditing an entire color palette for accessibility compliance
• Verifying colors extracted from a design meet WCAG standards

Instructions

1. Takes a list of hex colors as arguments
2. Computes the contrast ratio for every foreground/background pair
3. Tests each pair against WCAG 2.1 AA and AAA thresholds for normal and large text

WCAG thresholds:

• AA normal text — ratio >= 4.5:1
• AA large text — ratio >= 3:1
• AAA normal text — ratio >= 7:1
• AAA large text — ratio >= 4.5:1

Run the script with two or more hex colors (with or without # prefix):

bash <skill-path>/scripts/contrast-check.sh <color1> <color2> [color3] [color4] ...

The script outputs JSON with contrast ratios and pass/fail results:

{
  "pairs": [
    {
      "foreground": "#1a1a2e",
      "background": "#ffffff",
      "ratio": 16.57,
      "aa": { "normal": true, "large": true },
      "aaa": { "normal": true, "large": true }
    }
  ],
  "summary": {
    "totalPairs": 2,
    "passAA": 1,
    "passAAA": 1,
    "failAA": 1
  }
}

After checking, present a table to the user:

Contrast Check Results:

  #1a1a2e on #ffffff — 16.57:1 — AA: Pass — AAA: Pass
  #e94560 on #ffffff —  3.94:1 — AA: Fail (normal) / Pass (large) — AAA: Fail

Summary: 1/2 pairs pass AA for normal text, 1/2 pass AAA.

Flag any failing pairs and suggest fixes (darken/lighten the color to reach the threshold).

Examples

Example 1: Check a dark theme header against white text

bash <skill-path>/scripts/contrast-check.sh "#1a1a2e" "#ffffff"

Output:

{
  "pairs": [
    {
      "foreground": "#1a1a2e",
      "background": "#ffffff",
      "ratio": 16.57,
      "aa": { "normal": true, "large": true },
      "aaa": { "normal": true, "large": true }
    }
  ],
  "summary": { "totalPairs": 1, "passAA": 1, "passAAA": 1, "failAA": 0 }
}

Example 2: Audit a full brand palette

bash <skill-path>/scripts/contrast-check.sh "#1a1a2e" "#e94560" "#ffffff" "#3d83f7" "#bdbdbd"

The script checks all foreground/background combinations and reports which pairs fail AA or AAA. For example, #e94560 on #ffffff yields a ratio of 3.94:1 which fails AA for normal text but passes for large text.

Guidelines

• Colors must be valid hex values (3 or 6 digits, with or without #).
• Pair with the image-analysis skill to extract colors from a design first, then pipe the hex values into this skill to audit accessibility.
• When a pair fails, suggest darkening or lightening one of the colors to meet the target ratio.