Methodology & Accuracy

Every keepsake on this site is produced by a small, tested rendering engine, and every rule in that engine exists because we measured what happens when it is broken. This page documents those rules — what gets styled, what never does, and the limits we verified with a real decoder — so you can judge exactly how far to trust a decorated code.

The anatomy rule: landmarks are never decorated

A scanner finds a QR code by its three large corner squares (finder patterns) and orients dense codes with smaller inner squares (alignment patterns). Our testing showed that restyling alignment patterns breaks decoding outright — so in every KeepsakeCodes style, finder and alignment patterns are always rendered as classic, crisp squares. Timing tracks may be styled; the landmarks may not. The mandatory four-module quiet zone (the clear margin around the code) is always drawn and is never covered by frame art.

Maximum error correction, always

QR codes carry redundancy so damaged modules can be reconstructed. Plain codes often use the middle levels to stay small; artistic codes spend that redundancy on decoration. Every artistic style here therefore encodes at level H (roughly 30% recovery) without exception — the engine refuses to render an artistic style over a lower level.

Heart-module codes

Dark modules are redrawn as heart glyphs spanning 0.97 of their cell — large enough that a scanner's sampling grid still reads each cell as decisively dark, small enough that adjacent hearts read as separate shapes to the eye. Foreground and background must measure at least 4.5:1 in WCAG contrast; the engine rejects weaker pairs rather than warning, because scanners binarize the image and low contrast measurably hurts decoding.

Photo halftone codes

Each data cell is split into a small grid. The center half of the cell is authoritative: it is rendered in the pure module color, because decoders sample near cell centers. Our measurements fixed this at 50% of the cell — at 40%, decoding fails. The outer ring of the cell displays your photo, quantized to three tones (dark, mid, light) at luminance thresholds of 85 and 175 on the 0–255 scale, so the picture stays visible without inventing false modules. Finder, alignment, and timing cells plus the quiet zone stay fully pure, and no logo may be stacked on a halftone code — the photo already spends the decode margin.

Framed codes

The safest style by construction: the code itself is not modified at all. It sits, quiet zone included, on an opaque clean panel drawn above the frame art, so decoration can never touch a module. Frames (heart, floral, ring, classic, confetti) are recolorable vector art; changing the palette cannot affect the code.

Every render is decode-verified

Rules make failure unlikely; verification makes it visible. After each render, your browser rasterizes the finished artwork — frame, hearts, photo and all — and runs a real QR decoder (jsQR) on the pixels, then compares the decoded bytes to your exact content. A match shows the "Verified scannable" badge; anything else shows a clear warning and keeps the downloads locked, so an unverified render cannot leave the page as a finished keepsake.

Tested the same way, automatically

The engine's test suite runs the identical render-rasterize-decode loop on every style — at several raster sizes, rotated, and after lossy JPEG re-compression — and requires the decoded bytes to match exactly. The measured limits above (the 0.97 heart coverage, the 50% halftone center, the alignment-pattern rule) are pinned by these tests, so a future change that breaks scannability fails the build instead of shipping.

Worked examples can't drift

The example codes shown on tool pages are rendered at build time by the same engine that powers the interactive generators — never pasted-in images. If the rendering logic changed, the page art would change with it (or the build would fail), so the documentation cannot silently disagree with the tool.

What verification cannot promise

On-screen verification proves the artwork decodes cleanly at screen resolution. It cannot see your printer, your paper, or the phone that will do the scanning. Print at least 2 × 2 cm for arm's-length scanning, keep the quiet zone uncropped, and scan a test print with a real phone before the moment that matters. If a verified code will not scan in print, that is exactly the report we want — see the contact page; confirmed issues are fixed in the engine and locked in with a new test.