DEV Community: Chris Morris

Resolving color contrast over CSS gradients

Chris Morris — Mon, 20 Jul 2026 17:23:34 +0000

Run an automated accessibility check on a modern landing page and the headline often comes back as "needs review" rather than pass or fail. The usual reason is a gradient. Here is why that happens, and the small piece of maths that resolves most of it.

Why gradients become a blind spot

The contrast check in axe-core compares the colour of text against the colour behind it. To do that reliably it reads the computed background-color of the element and its ancestors, a single solid value it can reason about.

A CSS gradient is not a solid colour. It is set through background-image: linear-gradient(...), so when text sits directly on one, axe has no single background value to measure against. Rather than guess, it does the responsible thing and returns the result as incomplete, the "needs review" state. That is correct, but it has an awkward side effect: the text it punts on is frequently the most prominent text on the page, the hero headline sitting on a colourful gradient banner.

The insight: the worst case lives at a stop

You do not actually need to sample every pixel under the text to know whether it passes. A gradient is fully defined by its colour stops. Between any two adjacent stops the colour moves smoothly from one to the other, and contrast against a fixed text colour changes smoothly with it. There is no hidden spike in the middle.

That means the lowest contrast, the worst case, has to occur at one of the stops. So the whole question reduces to: compute the contrast between the text colour and each stop, take the smallest, and compare it to the threshold. If the worst stop passes, the text passes across the entire gradient. If the worst stop fails, you have a real failure with a real number.

The WCAG contrast maths

The thresholds come from WCAG 1.4.3 Contrast (Minimum): a ratio of at least 4.5:1 for normal text, or 3:1 for large text (24px and up, or 18.66px and up when bold). The ratio itself is built from relative luminance.

Each channel is linearised, then weighted:

// 0–255 channel → linear light
const lin = (c) => { c /= 255; return c <= 0.03928 ? c/12.92 : Math.pow((c+0.055)/1.055, 2.4); };
// relative luminance
const lum = (c) => 0.2126*lin(c.r) + 0.7152*lin(c.g) + 0.0722*lin(c.b);
// contrast ratio between two colours
const contrast = (a, b) => {
  const hi = Math.max(lum(a), lum(b)), lo = Math.min(lum(a), lum(b));
  return (hi + 0.05) / (lo + 0.05);
};

This is the same formula axe uses for solid backgrounds. We are not changing how contrast is judged, only giving it the right colours to judge.

The algorithm, step by step

For each element axe left as "needs review" for colour contrast:

Read the computed color (the text) and the font size and weight, which set the required ratio (4.5 or 3).
Walk up the ancestors to find the nearest element whose computed background-image actually contains gradient(.
Pull the colour stops out of that value. Browsers compute keywords and hex to rgb() / rgba(), so the stops are already concrete numbers.
Compute the contrast between the text colour and each stop, and keep the minimum.
If that worst-case ratio is below the requirement, it is a genuine failure. If it clears the bar, the text passes across the whole gradient, so the "needs review" can be dropped entirely.

let worst = Infinity;
for (const stop of stops) worst = Math.min(worst, contrast(textColor, stop));
if (worst < required) {
  // real failure, e.g. "lowest-contrast point is 1.37:1, below the required 3:1"
}

The result is that a headline which used to come back as an unknown now comes back as "fails at 1.37:1", with the exact element, which is something a developer can actually act on.

Where it stops: the honest limits

This resolves opaque CSS gradients, and deliberately nothing more. Two cases are left as "needs review" on purpose:

Background images. If the background is a url() photo, the effective colour under the text cannot be derived from CSS. That genuinely needs pixel sampling, which is a separate problem.
Semi-transparent stops. If any stop has an alpha below 1, the real colour depends on whatever sits behind it, so the stops alone are not enough.

It also does not try to account for text shadows, blend modes, or text that overlaps a gradient edge. The rule we hold to is simple: resolve what can be proven from the CSS, and honestly flag the rest for a human. Claiming more than the maths supports would just be a prettier version of the "needs review" problem.

Why it matters

Gradients are everywhere in modern design, and they tend to sit behind the text that matters most. Leaving all of it as "needs review" pushes the single most visible contrast decision onto a manual pass that often never happens. Resolving the opaque-gradient case turns a common blind spot into a concrete pass or fail, and it is the kind of detail that separates a tool that runs axe from one that does something useful with the output. You can see it on your own pages with the free scan, or wire it into CI with the CLI and GitHub Action.

FAQ

Why does axe-core mark gradient text as "needs review"?

Because its contrast check reads a solid background-color, and a gradient is set via background-image. With no single background value, axe correctly returns the result as incomplete rather than guessing.

Why is checking the gradient stops enough?

Contrast against a fixed text colour changes smoothly between stops, so the lowest contrast must occur at a stop. Checking each stop and taking the worst case covers the entire gradient without sampling pixels.

Does this work for background images?

No. The effective colour under text on a photo cannot be derived from CSS, so image backgrounds (and semi-transparent gradients) are left as "needs review". Resolving those needs pixel sampling.

What contrast ratios are required?

WCAG 1.4.3 requires 4.5:1 for normal text and 3:1 for large text (24px and up, or 18.66px and up if bold).

I build a few products. This one is Accessibility Scanner, a free, honest WCAG scanner with no overlay and no fake compliance badge.

Turning a web tool into a zero-dependency MCP server

Chris Morris — Fri, 03 Jul 2026 21:44:41 +0000

I run DomainIntel, a small web app that analyzes any
domain: WHOIS, DNS, SSL/TLS, HTTP security headers, blocklist reputation, and
subdomain discovery. The analysis engine was already there as a set of Node
modules behind an Express API. The question was: how do I let AI agents use it
directly, without standing up a whole new service?

The answer was the Model Context Protocol
(MCP). This post is the practical, gotcha-heavy version of how I shipped it as
npx -y @domainintel/mcp — a single file with no runtime dependencies.

The shape of it

MCP servers expose "tools" an agent can call. I wrapped each analyzer as one:
whois_lookup, dns_records, ssl_certificate, security_headers,
domain_reputation, subdomain_discovery, and a full_domain_report that runs
everything and returns an overall score. Each takes a domain and returns
structured JSON. The whole server is ~150 lines on top of the existing analyzers
and the MCP SDK's stdio transport.

The interesting part wasn't the MCP code. It was packaging.

Goal: `npx` with no install friction

I wanted a user to run npx -y @domainintel/mcp and have it work — no clone, no
npm install of a dependency tree. That means bundling the server and the
analyzer graph it reuses into one self-contained file. I used esbuild. Four
things bit me; all are general to "bundle a Node CLI that reuses CommonJS code
into an ESM binary."

1. createRequire so a bundler can follow your imports

My server originally pulled the analyzers in with createRequire:

const require = createRequire(import.meta.url);
const { analyzeDns } = require('../lib/analyzers/dns');

esbuild can't follow a runtime createRequire call — it only sees static
imports. So nothing got bundled. The fix was to switch to static default
imports, which Node's ESM loader maps to a CommonJS module's module.exports:

import dnsPkg from '../lib/analyzers/dns.js';
const { analyzeDns } = dnsPkg;

Now esbuild follows the graph, and node server.mjs still works in dev.

2. Node built-ins under ESM output: "Dynamic require of 'net' is not supported"

One dependency (whois) calls require('net') internally. In esbuild's ESM
output there's no require, so it throws at runtime. The fix is a banner that
defines one via createRequire, which esbuild's shim then uses for built-ins:

banner: {
  js: [
    '#!/usr/bin/env node',
    "import { createRequire as __cr } from 'module';",
    'const require = __cr(import.meta.url);'
  ].join('\n')
}

3. stdout belongs to the protocol — don't log to it

MCP over stdio uses stdout for the JSON-RPC stream. My analyzers' shared logger
wrote to a logs/ directory, which is also wrong for a globally-installed CLI
(it would try to mkdir inside the npm install dir). I swapped it at build time
for a stderr-only stub using an esbuild onResolve plugin, so the real app keeps
file logging and the bundle stays quiet on stdout:

build.onResolve({ filter: /utils[\\/]errorLogger(\.js)?$/ }, () => ({ path: stub }));

4. The small stuff

Two shebangs. The entry file had #!/usr/bin/env node and the banner added one, so the bundle's line 2 was an invalid #. Drop it from the source.
"type": "module" + CommonJS. When I vendored the analyzers into a standalone repo whose package.json had "type": "module", esbuild treated the CJS .js files as ESM and choked on module.exports. Removing "type": "module" (the .mjs entry stays ESM by extension) fixed it.
A dependency going ESM. whois@2.16 switched to ESM, which broke the non-bundled require('whois') dev path. Pinning to 2.15.0 kept both the dev path and a reproducible bundle.

Result

mcp/dist/server.mjs is one ~1.7 MB file, zero runtime dependencies. Install:

claude mcp add domainintel -- npx -y @domainintel/mcp

Then your agent can run "give me a full report on stripe.com" and get
structured results instead of shelling out to dig/whois and parsing text.

If you maintain a tool with a usable core, wrapping it as an MCP server is a
small lift, and bundling it to a single file makes it genuinely one-command to
adopt. Source is on GitHub —
happy to answer questions about any of the above.

Almost half the WordPress plugin directory has not been updated in two years

Chris Morris — Sat, 27 Jun 2026 22:57:10 +0000

I indexed the WordPress.org plugin directory and measured how well it is maintained. The headline: of the 57,383 plugins in the index, 45.6 percent have not shipped an update in 24 or more months. Data is as of June 2026.

Here is the full staleness picture, measured against plugins that report an update date:

65 percent: no update in 6+ months
56 percent: no update in 12+ months
45.6 percent: no update in 24+ months
41.2 percent: no update in 36+ months

"Not updated in two years" is the common line for calling a plugin abandoned, and WordPress.org uses a similar signal when it warns you on a plugin page. So nearly half the directory carries that flag.

The interesting part is who goes stale

Abandonment is not evenly spread. It tracks inversely with install count:

Active installs	Abandoned (no update in 24+ months)
1K to 10K	23.9 percent
10K to 100K	10.1 percent
100K to 1M	2 percent
1M+	0 percent

The very large plugins are maintained. The risk and the opportunity sit in the middle. 192 plugins with 10,000 or more active installs have not been updated in over two years. Each one is a real user base running code nobody is shipping fixes for.

Why a builder should care

A plugin with 30,000 installs and no maintainer is not a dead end. It is a ready-made market. The users already exist, the search demand already exists, and the incumbent has stopped competing. The work is not inventing a category. It is shipping a maintained, modern version of something people already rely on.

That is a very different starting point from a cold launch. You are not asking whether anyone wants the thing. You are looking at the install count and reading the recent one-star reviews to find out exactly what to fix.

How to use this

If you are looking for a side project or a small product to build, abandoned mid-size plugins are a practical place to start. Pick a niche you understand, find a plugin in it with a stuck user base, read its support forum, and confirm the gap before you write any code.

The full report, with the named lists of the most-installed abandoned plugins, the most-installed low-rated plugins, and the largest plugins with the weakest support, is here:

The State of WordPress Plugin Opportunities 2026

The numbers above are measured from live WordPress.org data and the method is stated on the report.