DEV Community: Chris Morris

Resolving color contrast over CSS gradients

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

Correction, September 2026. The central claim in the original version of this post was wrong, and I have rewritten it. I said the worst-case contrast across a gradient always sits at one of its colour stops. That holds for light text and fails for dark text, because a blend of two colours can be darker than either one. My own scanner measured gradients this way and reported passes it should not have. The corrected method is below, along with the counterexample that found it.

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, a background photo, or a scrim over one. Here is why that happens, and how each of them gets resolved into an actual pass or fail.

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.

Why checking the stops is not enough

A gradient is fully defined by its colour stops, so the obvious shortcut is to measure the text against each stop and take the worst result. That is what I originally built, and what this post originally recommended. For light text it holds. For dark text it can pass a gradient that fails.

The reason is how browsers blend. Between two stops, a gradient written with ordinary colours mixes the red, green and blue values as they are stored, not as amounts of light. Luminance, which the WCAG ratio is built on, curves against those stored values, so a mix of two colours can come out darker than either of them.

Take black text on linear-gradient(90deg, #ff0000, #00c800). Against the red stop it measures 5.25:1, and against the green stop 9.26:1. Both pass. About 37% of the way across, the blend is a muddy brown and the ratio there is 3.49:1, which fails. Checking only the stops reports a pass on text that is genuinely too dark to read against part of its own background.

The same curve explains why light text was never affected. Luminance along one of these segments is convex, so its maximum is always at a stop. The minimum is the one that can hide in the middle.

So the check has to sample along each stretch between stops, blending in the same colour space the browser uses, and keep the lowest value it finds.

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 that actually paints a background: a gradient(, a url() image, or a colour.
Pull the colour stops out of that value. This part is fussier than it looks. It is tempting to match rgb() and rgba() with a regular expression, but current CSS computes colours to color(srgb ...), oklch(), lab() and color-mix(), and Tailwind v4 emits those by default. A regex quietly finds nothing on a modern site and the whole check falls back to "needs review". So each colour token is painted to a one-pixel canvas and read back instead, which works for any syntax the browser itself understands.
Sample each segment between adjacent stops, mixing in the space the browser uses for that gradient, and keep the minimum contrast across every stop and sample.
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 (let i = 0; i < stops.length - 1; i++) {
  worst = Math.min(worst, contrast(textColor, stops[i]));
  for (let s = 1; s < SAMPLES; s++) {
    // mix in the colour space the browser blends this gradient in
    const bg = mix(stops[i], stops[i + 1], s / SAMPLES);
    worst = Math.min(worst, contrast(textColor, bg));
  }
}
worst = Math.min(worst, contrast(textColor, stops[stops.length - 1]));
if (worst < required) {
  // real failure, e.g. "lowest-contrast point is 3.49:1, below the required 4.5:1"
}

Which space to mix in matters. A gradient can name one (in srgb, in oklab), and otherwise the default depends on the syntax of its stops: sRGB when they are all written in legacy notation, Oklab when any of them uses CSS Color 4 notation. A hard edge, where two stops sit at the same position, paints nothing between them, so nothing is sampled there.

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

Background images and translucent layers

Stops alone were never going to cover two very common cases, and both are now resolved as well.

Background images. The colour under text on a photo cannot be derived from the stylesheet, so the image is decoded onto a canvas and the pixels underneath the text are sampled directly. The element box, background-size, background-position and background-repeat together say which part of the image is actually behind the text, and the worst contrast across that region decides. A headline that is readable over the dark half of a photo and invisible over the light half is a real failure, and averaging would hide exactly that.

Translucent layers. A dark scrim over a hero photo is the standard way to make white text work. If a stop or an overlay has an alpha below 1, it gets composited over whatever sits beneath it, the same way the browser paints it, rather than being abandoned as unknowable.

What still stays "needs review"

Plenty is still left for a human, on purpose. A wrong "needs review" costs somebody a few minutes. A wrong "pass" tells them their site is fine when it is not, which is the whole problem with compliance badges. So anything that cannot be established is left alone:

Images from another domain. Reading pixels back from a canvas that has loaded a cross-origin image is blocked by the browser unless that server allows it.
Gradients blended in a hue-based space, such as in hsl or in oklch. The path the colour takes around the hue wheel is harder to reproduce exactly.
Any stop that will not parse. Dropping one silently could discard the very colour the text fails against, which is its own way of inventing a pass.
Gradients painted by a separate overlay element that merely sits on top of the text rather than being one of its ancestors, which is a common hero pattern.
Pseudo-element backgrounds, text partly covered by another element, fixed-attachment images, ancestor opacity, filters and blend modes, and text shadows.

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 it turns a common blind spot into a concrete pass or fail.

It also turned out to be a good lesson in checking a shortcut before trusting it. The stop-only version was fast, easy to reason about, and wrong in exactly the direction that matters, because a false pass is the thing an accessibility tool must never produce. You can try a gradient or a photo yourself in the contrast checker, which runs entirely in your browser, or scan a page with the free scan or 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.

Is checking the gradient stops enough?

For light text, yes: the lightest point of a blend is always at a stop. For dark text, no. Browsers blend the stored red, green and blue values, and the result can be darker than both stops, so dark text can pass at every stop and fail in between. Sample along each stretch between stops instead.

Does this work for background images?

Yes. The colour under text on a photo cannot be read from CSS, so the image is decoded onto a canvas and the pixels behind the text are sampled, with the worst contrast across that area deciding the result. Translucent overlays such as a scrim on a hero image are composited the way the browser paints them. An image served from another domain still cannot be sampled unless that server permits it.

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 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.