contrast-gate 1.0.0 → 1.1.0

package/README.md

@@ -59,8 +59,16 @@ Exit code is `1` if anything fails WCAG AA — which means it works as a CI gate
 |---|---|
 | `--json` | Print machine-readable JSON instead of a table |
 | `--aaa` | Require WCAG AAA (7:1 normal text) instead of AA (4.5:1) |
+| `--fix` | For each failing pair, suggest a corrected color that would pass |
 | `-h, --help` | Show usage |
 
+With `--fix`, a failing pair gets a suggested replacement color — the smaller of adjusting the foreground or the background, found by holding hue and saturation fixed and adjusting only lightness until the pair clears the threshold:
+
+```
+- Muted caption: 1.68:1 (#c8c0ae on #faf6ee) — needs at least 4.5:1
+    fix: change text color to #7d7055 → 4.51:1
+```
+
 ### Exit codes
 
 | Code | Meaning |
@@ -94,11 +102,14 @@ jobs:
 The contrast-calculation core is exported directly, if you want to check colors from your own code rather than a config file:
 
 ```ts
-import { contrastRatioHex, checkCompliance } from "contrast-gate";
+import { contrastRatioHex, checkCompliance, suggestFix } from "contrast-gate";
 
 const ratio = contrastRatioHex("#302a22", "#faf6ee"); // 13.16
 const result = checkCompliance(ratio);
 // { ratio: 13.16, passesAA: { normal: true, large: true }, passesAAA: { normal: true, large: true } }
+
+const fix = suggestFix("#c8c0ae", "#faf6ee", 4.5);
+// { fg: "#7d7055", bg: "#faf6ee", ratio: 4.51, adjusted: "fg" }
 ```
 
 ## How the math works

package/dist/src/cli.js

@@ -11,6 +11,7 @@ Usage:
 Options:
   --json          Output machine-readable JSON instead of a table
   --aaa           Require WCAG AAA (7:1 normal text) instead of AA (4.5:1) to pass
+  --fix           For each failing pair, suggest a corrected color that would pass
   -h, --help      Show this help message
 
 Example:
@@ -36,6 +37,7 @@ async function main() {
         options: {
             json: { type: "boolean", default: false },
             aaa: { type: "boolean", default: false },
+            fix: { type: "boolean", default: false },
             help: { type: "boolean", short: "h", default: false },
         },
         allowPositionals: true,
@@ -63,7 +65,7 @@ async function main() {
         renderJson(results);
     }
     else {
-        renderTable(results);
+        renderTable(results, values.fix);
     }
     process.exit(allPass ? 0 : 1);
 }

package/dist/src/core.d.ts

@@ -43,3 +43,4 @@ export interface PairResult extends ComplianceResult {
 }
 /** Evaluates a named list of foreground/background pairs in one pass. */
 export declare function evaluatePairs(pairs: ColorPair[]): PairResult[];
+export { suggestFix, type FixSuggestion } from "./suggest.js";

package/dist/src/core.js

@@ -69,3 +69,4 @@ export function evaluatePairs(pairs) {
         return { ...pair, ...checkCompliance(ratio) };
     });
 }
+export { suggestFix } from "./suggest.js";

package/dist/src/report.d.ts

@@ -1,5 +1,5 @@
 import type { PairResult } from "./core.js";
 /** Renders a human-readable colored table to stdout. */
-export declare function renderTable(results: PairResult[]): void;
+export declare function renderTable(results: PairResult[], showFixes?: boolean): void;
 /** Renders results as machine-readable JSON to stdout. */
 export declare function renderJson(results: PairResult[]): void;

package/dist/src/report.js

@@ -1,3 +1,4 @@
+import { suggestFix } from "./suggest.js";
 const RESET = "\x1b[0m";
 const GREEN = "\x1b[32m";
 const RED = "\x1b[31m";
@@ -10,7 +11,7 @@ function badge(pass) {
     return pass ? `${GREEN}PASS${RESET}` : `${RED}FAIL${RESET}`;
 }
 /** Renders a human-readable colored table to stdout. */
-export function renderTable(results) {
+export function renderTable(results, showFixes = false) {
     const nameWidth = Math.max(4, ...results.map((r) => r.name.length));
     console.log(`${BOLD}${pad("Pair", nameWidth)}  Ratio    AA Normal  AA Large  AAA Normal  AAA Large${RESET}`);
     console.log(DIM + "-".repeat(nameWidth + 58) + RESET);
@@ -27,6 +28,15 @@ export function renderTable(results) {
         console.log(`${RED}${failing.length} of ${results.length} pair(s) fail WCAG AA (normal text):${RESET}`);
         for (const f of failing) {
             console.log(`  - ${f.name}: ${f.ratio.toFixed(2)}:1 (${f.fg} on ${f.bg}) — needs at least 4.5:1`);
+            if (showFixes) {
+                const fix = suggestFix(f.fg, f.bg, 4.5);
+                if (fix.adjusted === "fg") {
+                    console.log(`    ${DIM}fix: change text color to ${fix.fg} → ${fix.ratio.toFixed(2)}:1${RESET}`);
+                }
+                else if (fix.adjusted === "bg") {
+                    console.log(`    ${DIM}fix: change background to ${fix.bg} → ${fix.ratio.toFixed(2)}:1${RESET}`);
+                }
+            }
         }
     }
 }

package/dist/src/suggest.d.ts

@@ -0,0 +1,12 @@
+export interface FixSuggestion {
+    fg: string;
+    bg: string;
+    ratio: number;
+    adjusted: "fg" | "bg" | "none";
+}
+/**
+ * Suggests the smallest lightness adjustment (to either fg or bg) that reaches
+ * targetRatio, preserving hue and saturation so the result still looks related
+ * to the original color. Picks whichever of fg/bg needs the smaller change.
+ */
+export declare function suggestFix(fgHex: string, bgHex: string, targetRatio?: number): FixSuggestion;

package/dist/src/suggest.js

@@ -0,0 +1,119 @@
+import { parseHexColor, contrastRatio } from "./core.js";
+function rgbToHsl({ r, g, b }) {
+    const rn = r / 255;
+    const gn = g / 255;
+    const bn = b / 255;
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    if (max === min)
+        return { h: 0, s: 0, l: l * 100 };
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    switch (max) {
+        case rn:
+            h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6;
+            break;
+        case gn:
+            h = ((bn - rn) / d + 2) / 6;
+            break;
+        default:
+            h = ((rn - gn) / d + 4) / 6;
+    }
+    return { h: h * 360, s: s * 100, l: l * 100 };
+}
+function hueToRgb(p, q, t) {
+    let tt = t;
+    if (tt < 0)
+        tt += 1;
+    if (tt > 1)
+        tt -= 1;
+    if (tt < 1 / 6)
+        return p + (q - p) * 6 * tt;
+    if (tt < 1 / 2)
+        return q;
+    if (tt < 2 / 3)
+        return p + (q - p) * (2 / 3 - tt) * 6;
+    return p;
+}
+function hslToRgb({ h, s, l }) {
+    const hn = h / 360;
+    const sn = s / 100;
+    const ln = l / 100;
+    if (sn === 0) {
+        const v = Math.round(ln * 255);
+        return { r: v, g: v, b: v };
+    }
+    const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+    const p = 2 * ln - q;
+    return {
+        r: Math.round(hueToRgb(p, q, hn + 1 / 3) * 255),
+        g: Math.round(hueToRgb(p, q, hn) * 255),
+        b: Math.round(hueToRgb(p, q, hn - 1 / 3) * 255),
+    };
+}
+function rgbToHex({ r, g, b }) {
+    const toHex = (n) => Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0");
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+/**
+ * Binary-searches lightness for `moving`, holding hue/saturation fixed, to find
+ * the smallest lightness change (in the direction away from `fixed`'s lightness)
+ * that reaches targetRatio against `fixed`. Returns null if even pure black/white
+ * can't reach the target (fixed is fundamentally too close to mid-gray... rare).
+ */
+function searchLightness(moving, fixed, targetRatio) {
+    const movingHsl = rgbToHsl(moving);
+    const fixed_l = rgbToHsl(fixed).l;
+    const original = movingHsl.l;
+    // To increase contrast, push `moving` further away from `fixed`'s lightness:
+    // if moving is already darker, the extreme to move toward is pure black; if lighter, pure white.
+    const extreme = original <= fixed_l ? 0 : 100;
+    const lightnessAt = (t) => original + t * (extreme - original); // t=0 -> original, t=1 -> extreme
+    const ratioAt = (t) => contrastRatio(hslToRgb({ ...movingHsl, l: lightnessAt(t) }), fixed);
+    if (ratioAt(1) < targetRatio)
+        return null; // even the extreme doesn't reach target
+    // ratioAt(t) is monotonically increasing in t. Find the minimal t (least change
+    // from the original color) that still clears the target -- a simple boundary search.
+    let lo = 0; // presumed not to satisfy (we only call this when currently failing)
+    let hi = 1; // verified above to satisfy
+    for (let i = 0; i < 40; i++) {
+        const mid = (lo + hi) / 2;
+        if (ratioAt(mid) >= targetRatio)
+            hi = mid;
+        else
+            lo = mid;
+    }
+    return hslToRgb({ ...movingHsl, l: lightnessAt(hi) });
+}
+/**
+ * Suggests the smallest lightness adjustment (to either fg or bg) that reaches
+ * targetRatio, preserving hue and saturation so the result still looks related
+ * to the original color. Picks whichever of fg/bg needs the smaller change.
+ */
+export function suggestFix(fgHex, bgHex, targetRatio = 4.5) {
+    const fg = parseHexColor(fgHex);
+    const bg = parseHexColor(bgHex);
+    const currentRatio = contrastRatio(fg, bg);
+    if (currentRatio >= targetRatio) {
+        return { fg: fgHex, bg: bgHex, ratio: currentRatio, adjusted: "none" };
+    }
+    const fgFix = searchLightness(fg, bg, targetRatio);
+    const bgFix = searchLightness(bg, fg, targetRatio);
+    const fgDelta = fgFix ? Math.abs(rgbToHsl(fgFix).l - rgbToHsl(fg).l) : Infinity;
+    const bgDelta = bgFix ? Math.abs(rgbToHsl(bgFix).l - rgbToHsl(bg).l) : Infinity;
+    if (fgFix && fgDelta <= bgDelta) {
+        return { fg: rgbToHex(fgFix), bg: bgHex, ratio: contrastRatio(fgFix, bg), adjusted: "fg" };
+    }
+    if (bgFix) {
+        return { fg: fgHex, bg: rgbToHex(bgFix), ratio: contrastRatio(fg, bgFix), adjusted: "bg" };
+    }
+    // Neither could reach target (only possible if fixed color is itself ~middle gray
+    // at an unreasonably high target ratio) -- return best-effort fg=black/white flip.
+    const blackRatio = contrastRatio({ r: 0, g: 0, b: 0 }, bg);
+    const whiteRatio = contrastRatio({ r: 255, g: 255, b: 255 }, bg);
+    return blackRatio >= whiteRatio
+        ? { fg: "#000000", bg: bgHex, ratio: blackRatio, adjusted: "fg" }
+        : { fg: "#ffffff", bg: bgHex, ratio: whiteRatio, adjusted: "fg" };
+}

package/dist/test/suggest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/suggest.test.js

@@ -0,0 +1,48 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { contrastRatioHex } from "../src/core.js";
+import { suggestFix } from "../src/suggest.js";
+test("suggestFix: a pair that already passes is returned unchanged", () => {
+    const result = suggestFix("#000000", "#ffffff", 4.5);
+    assert.equal(result.adjusted, "none");
+    assert.equal(result.fg, "#000000");
+    assert.equal(result.bg, "#ffffff");
+});
+test("suggestFix: the real failing example from our own README (1.68:1) gets fixed to actually pass", () => {
+    const before = contrastRatioHex("#c8c0ae", "#faf6ee");
+    assert.ok(before < 4.5, "sanity check: this pair should actually be failing before the fix");
+    const fix = suggestFix("#c8c0ae", "#faf6ee", 4.5);
+    assert.ok(fix.ratio >= 4.5, `suggested fix should reach the target, got ${fix.ratio}`);
+    // The suggestion must be independently re-verifiable, not just self-reported.
+    const actualRatio = contrastRatioHex(fix.fg, fix.bg);
+    assert.ok(Math.abs(actualRatio - fix.ratio) < 0.01, `suggested colors, when independently re-checked, should match the reported ratio`);
+});
+test("suggestFix: picks whichever of fg/bg needs the smaller lightness change", () => {
+    // #1a1a1a (L~10%) against #999999 (L~60%) at a demanding AAA target (7:1):
+    // pushing fg toward black has very little room left to work with, while bg
+    // has a wide range to move into. The smaller actual change is on bg's side --
+    // verified by computing both deltas directly, not assumed.
+    const fix = suggestFix("#1a1a1a", "#999999", 7);
+    assert.equal(fix.adjusted, "bg");
+    assert.ok(fix.ratio >= 7);
+});
+test("suggestFix: works with AAA target too, not just the AA default", () => {
+    const fix = suggestFix("#767676", "#ffffff", 7); // 4.54:1 passes AA but not AAA
+    assert.ok(fix.ratio >= 7, `expected AAA-level fix, got ${fix.ratio}`);
+});
+test("suggestFix: never returns a suggestion that fails to meet the target when re-verified", () => {
+    // Run across a spread of failing pairs and confirm every single suggestion
+    // actually holds up when independently recomputed -- not just trusted.
+    const cases = [
+        ["#aaaaaa", "#ffffff"],
+        ["#333333", "#000000"],
+        ["#c8c0ae", "#faf6ee"],
+        ["#ff0000", "#ff8080"],
+    ];
+    for (const [fg, bg] of cases) {
+        const fix = suggestFix(fg, bg, 4.5);
+        const reVerified = contrastRatioHex(fix.fg, fix.bg);
+        assert.ok(reVerified >= 4.49, // tiny float tolerance
+        `${fg}/${bg} -> suggested ${fix.fg}/${fix.bg} re-verifies to ${reVerified}, expected >= 4.5`);
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contrast-gate",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Audit an entire design-token file for WCAG contrast compliance in one command, and gate CI on it.",
   "type": "module",
   "bin": {