Why Artistic QR Codes Silently Fail (And How I'm Trying to Fix It)

#design #productivity #showdev #webdev

So I have been building a free browser-based QR code generator for the past few months. It supports custom gradients, image overlays, and different dot shapes. The results look cool—think nebula images fading into purple gradients.

I was happy... until I tried to actually use one.

The "iPhone Failure" 📱

I tried scanning one of my cooler designs on my iPhone and it just did not scan. At all. WhatsApp failed. Some Android scanners worked, some didn't.

I set the error correction to Level H (the max 30% recovery level). Still nothing.

The Real Culprit: Contrast Detection

I spent hours thinking it was a bug in my library. It wasn't.

Phone cameras don't read QR codes like humans. They use contrast algorithms to find the boundary between dark modules and the light background.

Your eyes: See two distinct colors.
The camera algorithm: Sees gray noise.

Error correction doesn't help because the modules aren't "missing"—they are just invisible to the scanner's logic.

My Solution: The MSQF Framework

To fix this, I’m building the Multi-Step QR Framework (MSQF). Instead of "generate and hope," it runs the QR through a verification pipeline:

1SQF (Internal): Scans with an internal engine. If it fails, it auto-adjusts opacity/contrast and retries.
2SQF (ZXing): Passes through Google’s open-source engine (common on Android).
3SQF (quirc-wasm): A stricter pass for edge cases.
4SQF (zxing-wasm Strict): My closest approximation to the iPhone's native camera behavior.

Technical Implementation Note

I don't make 4SQF the default because it takes significantly longer, especially for bulk generation. It allows users to choose the trade-off between "art" and "reliability."

I Need Your Advice 🤝

I’m still building this out, and I have two big questions for the community:

Engine Choices: Is zxing-wasm in strict mode really the best way to simulate the iPhone Vision framework?
The "Look" vs. "Function" Trade-off: When auto-adjusting, sometimes the design loses its "vibe" to make it scannable. Where would you draw the line?

Try the Generator (Free, No Signup)

I'd love to hear if anyone else has dealt with scan reliability for custom-styled QRs!