Gradient QR codes that still scan

The rule: judge the lightest stop, not the average

A decoder does not see a gradient; it sees each module at whatever luminance the gradient gives it locally. So a gradient passes only if both ends (and every stop between) satisfy the 40-point contrast rule against the background. The average being dark enough means nothing if one corner of the code fades to a pastel.

Worked example on white, using L = 0.2126R + 0.7152G + 0.0722B:

Stop	Hex	Luminance	Difference vs white	Verdict
Deep indigo	#312e81	21%	79	pass
Violet	#7c3aed	33%	67	pass
Light violet	#a78bfa	60%	40	on the floor, reject

An indigo-to-violet gradient (#312e81 → #7c3aed) is safe everywhere. Extend it to the light violet and the code's pale end sits exactly on the minimum with zero headroom for print or dim light, the kind of margin that produces codes that fail only sometimes.

Linear vs radial

Linear gradients spread the light end across one edge or corner of the code. At 45° one corner, including one finder pattern: gets the lightest ink, so the lightest stop must pass with room to spare.

Radial gradients are riskier than they look: with a dark centre fading outward, the corners are the lightest region, and all three finder patterns live in corners. If the eyes are the weakest-contrast part of the symbol, detection fails before decoding starts. Two fixes: keep the radial range narrow (both stops well past 40 points), or paint the eyes with a solid dark colour so they opt out of the gradient entirely.

Two further rules regardless of direction: the gradient belongs on the modules only: a gradient background gives the decoder no single threshold to find, the same failure as photographic backgrounds, and both stops should share a similar hue so the code reads as one object rather than patchwork.

Doing it in UseQR

Foreground gradients are a URL parameter, so a gradient style is shareable and reproducible:

fg=l45~312e81~7c3aed    linear, 45° rotation, two stops
fg=r~312e81~7c3aed      radial, centre to edge

Add eyefg=312e81 (and ballfg=) to hold the eyes at the darkest stop, the cheap insurance described above. Try it directly: a linear gradient code.

Then prove it: the validator rasterises the styled code and reads it back with a real decoder, which is the only test that accounts for the gradient's weakest point, the eye colours and the styling together. UseQR runs the same decode-verify check before every download, but re-verify after any recolouring in a design tool.

FAQ

Do gradient QR codes scan?

Yes, when every stop of the gradient keeps at least a 40 percentage-point luminance difference against the background. Codes fail when the light end of the gradient drifts too close to the background, the average colour being dark enough is not sufficient.

Should the gradient be on the modules or the background?

The modules only. A gradient background varies the luminance the decoder must threshold against, which can make different regions of the code binarise inconsistently. Keep the background solid and light: white is the safe default.

Are radial gradients worse than linear ones?

Slightly, in one specific way: a dark-centre radial gradient makes the corners the lightest region, and the three finder patterns sit in corners. Keeping the eyes a solid dark colour removes that risk and costs nothing visually.

How do I test a gradient QR code?

Decode the final rendered file with a validator, not just your own phone. A real decoder pass proves the lightest stop, the eye colours and the module styling work together, and testing a printed sample under dim light confirms the headroom survives production.