contrast-gate 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chandra Pratap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# contrast-gate
+
+Audit your entire design-token file for WCAG contrast compliance in one command, and fail CI when something doesn't meet the bar — instead of manually checking colors one pair at a time.
+
+Zero runtime dependencies.
+
+## Why this exists
+
+Contrast-ratio calculators already exist as libraries you import into code. What's missing is a standalone tool that checks your **whole set of design tokens at once** and plugs straight into CI — so a color that fails accessibility never gets shipped, the same way a failing test or lint error wouldn't.
+
+## Install
+
+```bash
+npm install --save-dev contrast-gate
+```
+
+Or run it without installing:
+
+```bash
+npx contrast-gate wcag.config.json
+```
+
+## Usage
+
+Create a config file listing the foreground/background pairs your product actually uses:
+
+```json
+{
+  "pairs": [
+    { "name": "Body text", "fg": "#302a22", "bg": "#faf6ee" },
+    { "name": "Primary button", "fg": "#ffffff", "bg": "#667355" },
+    { "name": "Muted caption", "fg": "#c8c0ae", "bg": "#faf6ee" }
+  ]
+}
+```
+
+Run it:
+
+```bash
+contrast-gate wcag.config.json
+```
+
+```
+Pair             Ratio    AA Normal  AA Large  AAA Normal  AAA Large
+-----------------------------------------------------------------------
+Body text        13.16:1  PASS       PASS      PASS        PASS
+Primary button   5.06:1   PASS       PASS      FAIL        PASS
+Muted caption    1.68:1   FAIL       FAIL      FAIL        FAIL
+
+1 of 3 pair(s) fail WCAG AA (normal text):
+  - Muted caption: 1.68:1 (#c8c0ae on #faf6ee) — needs at least 4.5:1
+```
+
+Exit code is `1` if anything fails WCAG AA — which means it works as a CI gate with zero extra scripting.
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--json` | Print machine-readable JSON instead of a table |
+| `--aaa` | Require WCAG AAA (7:1 normal text) instead of AA (4.5:1) |
+| `-h, --help` | Show usage |
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Every pair passes the selected level |
+| `1` | At least one pair fails |
+| `2` | Config file error (missing, malformed, or invalid) |
+
+## CI integration
+
+GitHub Actions example — fail the build if any color pair drops below WCAG AA:
+
+```yaml
+name: Accessibility
+
+on: [push, pull_request]
+
+jobs:
+  contrast:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx contrast-gate wcag.config.json
+```
+
+## Using it as a library
+
+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";
+
+const ratio = contrastRatioHex("#302a22", "#faf6ee"); // 13.16
+const result = checkCompliance(ratio);
+// { ratio: 13.16, passesAA: { normal: true, large: true }, passesAAA: { normal: true, large: true } }
+```
+
+## How the math works
+
+Implements the WCAG 2.1 relative luminance and contrast ratio formulas exactly as specified:
+- [Relative luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance)
+- [Contrast ratio](https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio)
+
+Verified against known reference values (black-on-white computes to exactly 21:1, the maximum possible ratio; `#767676` on white computes to ~4.54:1, a commonly cited borderline-AA gray).
+
+## License
+
+MIT

package/bin/contrast-gate.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/src/cli.js";

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { loadConfig, ConfigError } from "./config.js";
+import { evaluatePairs } from "./core.js";
+import { renderTable, renderJson } from "./report.js";
+const HELP = `contrast-gate — audit a design-token file for WCAG contrast compliance
+
+Usage:
+  contrast-gate <config-file> [options]
+
+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
+  -h, --help      Show this help message
+
+Example:
+  contrast-gate wcag.config.json
+  contrast-gate wcag.config.json --json > report.json
+
+Config file format:
+  {
+    "pairs": [
+      { "name": "Primary button", "fg": "#ffffff", "bg": "#667355" },
+      { "name": "Body text",      "fg": "#302a22", "bg": "#faf6ee" }
+    ]
+  }
+
+Exit codes:
+  0   every pair passes the selected level
+  1   at least one pair fails the selected level
+  2   config file error (missing, malformed, or invalid)
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        args: process.argv.slice(2),
+        options: {
+            json: { type: "boolean", default: false },
+            aaa: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+        allowPositionals: true,
+    });
+    if (values.help || positionals.length === 0) {
+        console.log(HELP);
+        process.exit(values.help ? 0 : 2);
+    }
+    const configPath = positionals[0];
+    let config;
+    try {
+        config = await loadConfig(configPath);
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            console.error(`contrast-gate: ${err.message}`);
+            process.exit(2);
+        }
+        throw err;
+    }
+    const results = evaluatePairs(config.pairs);
+    const level = values.aaa ? "passesAAA" : "passesAA";
+    const allPass = results.every((r) => r[level].normal);
+    if (values.json) {
+        renderJson(results);
+    }
+    else {
+        renderTable(results);
+    }
+    process.exit(allPass ? 0 : 1);
+}
+main().catch((err) => {
+    console.error("contrast-gate: unexpected error —", err);
+    process.exit(2);
+});

package/dist/src/config.d.ts

@@ -0,0 +1,8 @@
+import type { ColorPair } from "./core.js";
+export interface Config {
+    pairs: ColorPair[];
+}
+export declare class ConfigError extends Error {
+}
+/** Loads and validates a contrast-gate config file. Throws ConfigError on any malformed input. */
+export declare function loadConfig(path: string): Promise<Config>;

package/dist/src/config.js

@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+export class ConfigError extends Error {
+}
+/** Loads and validates a contrast-gate config file. Throws ConfigError on any malformed input. */
+export async function loadConfig(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        throw new ConfigError(`Could not read config file at "${path}": ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ConfigError(`Config file at "${path}" is not valid JSON: ${err.message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || !("pairs" in parsed)) {
+        throw new ConfigError(`Config file must be an object with a "pairs" array.`);
+    }
+    const pairsRaw = parsed.pairs;
+    if (!Array.isArray(pairsRaw) || pairsRaw.length === 0) {
+        throw new ConfigError(`Config "pairs" must be a non-empty array.`);
+    }
+    const pairs = pairsRaw.map((entry, index) => {
+        if (typeof entry !== "object" ||
+            entry === null ||
+            typeof entry.name !== "string" ||
+            typeof entry.fg !== "string" ||
+            typeof entry.bg !== "string") {
+            throw new ConfigError(`Config "pairs[${index}]" must have string "name", "fg", and "bg" fields.`);
+        }
+        return entry;
+    });
+    return { pairs };
+}

package/dist/src/core.d.ts

@@ -0,0 +1,45 @@
+/**
+ * WCAG 2.1 contrast calculation — relative luminance + contrast ratio,
+ * per https://www.w3.org/TR/WCAG21/#dfn-relative-luminance and
+ * https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+ */
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}
+export type ThresholdLevel = "AA" | "AAA";
+export type TextSize = "normal" | "large";
+/** Parses a hex color string (#fff, #ffffff, with or without leading #) into RGB. */
+export declare function parseHexColor(hex: string): RGB;
+/** WCAG relative luminance of an RGB color, in the range [0, 1]. */
+export declare function relativeLuminance({ r, g, b }: RGB): number;
+/** WCAG contrast ratio between two colors, in the range [1, 21]. */
+export declare function contrastRatio(a: RGB, b: RGB): number;
+/** Contrast ratio directly from two hex color strings. */
+export declare function contrastRatioHex(fgHex: string, bgHex: string): number;
+export interface ComplianceResult {
+    ratio: number;
+    passesAA: {
+        normal: boolean;
+        large: boolean;
+    };
+    passesAAA: {
+        normal: boolean;
+        large: boolean;
+    };
+}
+/** Full pass/fail breakdown for a contrast ratio against all four WCAG thresholds. */
+export declare function checkCompliance(ratio: number): ComplianceResult;
+export interface ColorPair {
+    name: string;
+    fg: string;
+    bg: string;
+}
+export interface PairResult extends ComplianceResult {
+    name: string;
+    fg: string;
+    bg: string;
+}
+/** Evaluates a named list of foreground/background pairs in one pass. */
+export declare function evaluatePairs(pairs: ColorPair[]): PairResult[];

package/dist/src/core.js

@@ -0,0 +1,71 @@
+/**
+ * WCAG 2.1 contrast calculation — relative luminance + contrast ratio,
+ * per https://www.w3.org/TR/WCAG21/#dfn-relative-luminance and
+ * https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
+ */
+const THRESHOLDS = {
+    AA: { normal: 4.5, large: 3 },
+    AAA: { normal: 7, large: 4.5 },
+};
+/** Parses a hex color string (#fff, #ffffff, with or without leading #) into RGB. */
+export function parseHexColor(hex) {
+    const cleaned = hex.trim().replace(/^#/, "");
+    const expanded = cleaned.length === 3
+        ? cleaned
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : cleaned;
+    if (!/^[0-9a-fA-F]{6}$/.test(expanded)) {
+        throw new Error(`Invalid hex color: "${hex}"`);
+    }
+    return {
+        r: parseInt(expanded.slice(0, 2), 16),
+        g: parseInt(expanded.slice(2, 4), 16),
+        b: parseInt(expanded.slice(4, 6), 16),
+    };
+}
+function channelToLinear(channel) {
+    const c = channel / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+/** WCAG relative luminance of an RGB color, in the range [0, 1]. */
+export function relativeLuminance({ r, g, b }) {
+    const rLin = channelToLinear(r);
+    const gLin = channelToLinear(g);
+    const bLin = channelToLinear(b);
+    return 0.2126 * rLin + 0.7152 * gLin + 0.0722 * bLin;
+}
+/** WCAG contrast ratio between two colors, in the range [1, 21]. */
+export function contrastRatio(a, b) {
+    const l1 = relativeLuminance(a);
+    const l2 = relativeLuminance(b);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/** Contrast ratio directly from two hex color strings. */
+export function contrastRatioHex(fgHex, bgHex) {
+    return contrastRatio(parseHexColor(fgHex), parseHexColor(bgHex));
+}
+/** Full pass/fail breakdown for a contrast ratio against all four WCAG thresholds. */
+export function checkCompliance(ratio) {
+    return {
+        ratio,
+        passesAA: {
+            normal: ratio >= THRESHOLDS.AA.normal,
+            large: ratio >= THRESHOLDS.AA.large,
+        },
+        passesAAA: {
+            normal: ratio >= THRESHOLDS.AAA.normal,
+            large: ratio >= THRESHOLDS.AAA.large,
+        },
+    };
+}
+/** Evaluates a named list of foreground/background pairs in one pass. */
+export function evaluatePairs(pairs) {
+    return pairs.map((pair) => {
+        const ratio = contrastRatioHex(pair.fg, pair.bg);
+        return { ...pair, ...checkCompliance(ratio) };
+    });
+}

package/dist/src/report.d.ts

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

package/dist/src/report.js

@@ -0,0 +1,36 @@
+const RESET = "\x1b[0m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+function pad(text, width) {
+    return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function badge(pass) {
+    return pass ? `${GREEN}PASS${RESET}` : `${RED}FAIL${RESET}`;
+}
+/** Renders a human-readable colored table to stdout. */
+export function renderTable(results) {
+    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);
+    for (const r of results) {
+        const ratioStr = pad(`${r.ratio.toFixed(2)}:1`, 8);
+        console.log(`${pad(r.name, nameWidth)}  ${ratioStr} ${badge(r.passesAA.normal)}       ${badge(r.passesAA.large)}      ${badge(r.passesAAA.normal)}        ${badge(r.passesAAA.large)}`);
+    }
+    const failing = results.filter((r) => !r.passesAA.normal);
+    console.log("");
+    if (failing.length === 0) {
+        console.log(`${GREEN}All ${results.length} pair(s) pass WCAG AA (normal text).${RESET}`);
+    }
+    else {
+        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`);
+        }
+    }
+}
+/** Renders results as machine-readable JSON to stdout. */
+export function renderJson(results) {
+    console.log(JSON.stringify({ results, allPassAA: results.every((r) => r.passesAA.normal) }, null, 2));
+}

package/dist/test/config.test.d.ts

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

package/dist/test/config.test.js

@@ -0,0 +1,37 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { writeFile, unlink } from "node:fs/promises";
+import { loadConfig, ConfigError } from "../src/config.js";
+const TMP_PATH = "./test/.tmp-config.json";
+test("loadConfig: loads a valid config file", async () => {
+    await writeFile(TMP_PATH, JSON.stringify({
+        pairs: [{ name: "Body text", fg: "#000000", bg: "#ffffff" }],
+    }));
+    const config = await loadConfig(TMP_PATH);
+    assert.equal(config.pairs.length, 1);
+    assert.equal(config.pairs[0].name, "Body text");
+    await unlink(TMP_PATH);
+});
+test("loadConfig: throws ConfigError for a missing file", async () => {
+    await assert.rejects(() => loadConfig("./does-not-exist.json"), ConfigError);
+});
+test("loadConfig: throws ConfigError for invalid JSON", async () => {
+    await writeFile(TMP_PATH, "{ not valid json");
+    await assert.rejects(() => loadConfig(TMP_PATH), ConfigError);
+    await unlink(TMP_PATH);
+});
+test("loadConfig: throws ConfigError when pairs is missing", async () => {
+    await writeFile(TMP_PATH, JSON.stringify({}));
+    await assert.rejects(() => loadConfig(TMP_PATH), ConfigError);
+    await unlink(TMP_PATH);
+});
+test("loadConfig: throws ConfigError when pairs is empty", async () => {
+    await writeFile(TMP_PATH, JSON.stringify({ pairs: [] }));
+    await assert.rejects(() => loadConfig(TMP_PATH), ConfigError);
+    await unlink(TMP_PATH);
+});
+test("loadConfig: throws ConfigError when a pair entry is malformed", async () => {
+    await writeFile(TMP_PATH, JSON.stringify({ pairs: [{ name: "Missing colors" }] }));
+    await assert.rejects(() => loadConfig(TMP_PATH), ConfigError);
+    await unlink(TMP_PATH);
+});

package/dist/test/core.test.d.ts

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

package/dist/test/core.test.js

@@ -0,0 +1,66 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseHexColor, relativeLuminance, contrastRatio, contrastRatioHex, checkCompliance, evaluatePairs, } from "../src/core.js";
+test("parseHexColor handles 6-digit and 3-digit hex, with or without #", () => {
+    assert.deepEqual(parseHexColor("#ffffff"), { r: 255, g: 255, b: 255 });
+    assert.deepEqual(parseHexColor("ffffff"), { r: 255, g: 255, b: 255 });
+    assert.deepEqual(parseHexColor("#fff"), { r: 255, g: 255, b: 255 });
+    assert.deepEqual(parseHexColor("#000"), { r: 0, g: 0, b: 0 });
+});
+test("parseHexColor rejects invalid input", () => {
+    assert.throws(() => parseHexColor("not-a-color"));
+    assert.throws(() => parseHexColor("#12345"));
+});
+test("relativeLuminance: white is 1, black is 0", () => {
+    assert.equal(relativeLuminance({ r: 255, g: 255, b: 255 }), 1);
+    assert.equal(relativeLuminance({ r: 0, g: 0, b: 0 }), 0);
+});
+test("contrastRatio: black on white is the maximum possible, 21:1", () => {
+    const ratio = contrastRatio({ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 });
+    assert.equal(ratio, 21);
+});
+test("contrastRatio: identical colors is the minimum possible, 1:1", () => {
+    const white = { r: 255, g: 255, b: 255 };
+    assert.equal(contrastRatio(white, white), 1);
+});
+test("contrastRatio is symmetric (order of arguments doesn't matter)", () => {
+    const black = { r: 0, g: 0, b: 0 };
+    const white = { r: 255, g: 255, b: 255 };
+    assert.equal(contrastRatio(black, white), contrastRatio(white, black));
+});
+test("contrastRatioHex: #767676 on white is ~4.54:1 (the well-known borderline AA gray)", () => {
+    const ratio = contrastRatioHex("#767676", "#ffffff");
+    assert.ok(Math.abs(ratio - 4.54) < 0.01, `expected ~4.54, got ${ratio}`);
+});
+test("checkCompliance: 4.54:1 passes AA normal text and AAA large text, but not AAA normal text", () => {
+    const result = checkCompliance(4.542224959605253);
+    assert.equal(result.passesAA.normal, true);
+    assert.equal(result.passesAA.large, true);
+    assert.equal(result.passesAAA.normal, false, "4.54:1 is below the 7:1 AAA normal threshold");
+    assert.equal(result.passesAAA.large, true, "4.54:1 is above the 4.5:1 AAA large threshold");
+});
+test("checkCompliance: #777777 on white (~4.48:1) fails AA normal text", () => {
+    const ratio = contrastRatioHex("#777777", "#ffffff");
+    const result = checkCompliance(ratio);
+    assert.equal(result.passesAA.normal, false, "4.48:1 should fail the 4.5:1 AA normal threshold");
+    assert.equal(result.passesAA.large, true, "4.48:1 should still pass the 3:1 AA large threshold");
+});
+test("checkCompliance: black on white (21:1) passes every threshold", () => {
+    const result = checkCompliance(21);
+    assert.equal(result.passesAA.normal, true);
+    assert.equal(result.passesAA.large, true);
+    assert.equal(result.passesAAA.normal, true);
+    assert.equal(result.passesAAA.large, true);
+});
+test("evaluatePairs: evaluates a named list end to end", () => {
+    const results = evaluatePairs([
+        { name: "Body text", fg: "#000000", bg: "#ffffff" },
+        { name: "Borderline gray", fg: "#767676", bg: "#ffffff" },
+        { name: "Failing gray", fg: "#777777", bg: "#ffffff" },
+    ]);
+    assert.equal(results.length, 3);
+    assert.equal(results[0].name, "Body text");
+    assert.equal(results[0].passesAAA.normal, true);
+    assert.equal(results[1].passesAA.normal, true);
+    assert.equal(results[2].passesAA.normal, false);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "contrast-gate",
+  "version": "1.0.0",
+  "description": "Audit an entire design-token file for WCAG contrast compliance in one command, and gate CI on it.",
+  "type": "module",
+  "bin": {
+    "contrast-gate": "bin/contrast-gate.js"
+  },
+  "main": "./dist/src/core.js",
+  "types": "./dist/src/core.d.ts",
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "pretest": "tsc",
+    "test": "node --test dist/test/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "wcag",
+    "accessibility",
+    "a11y",
+    "contrast",
+    "design-tokens",
+    "design-system",
+    "cli",
+    "ci"
+  ],
+  "author": "Chandra Pratap",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cptechstack/contrast-gate.git"
+  },
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/node": "^22.9.0"
+  }
+}