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.

How a message keepsake is encoded

A QR code containing bare text carries no scheme, so a phone has nothing to act on. Apple's Camera and Google's ML Kit both recognise links, phone numbers, email addresses, contact cards, calendar events and Wi-Fi joins — and no plain-text type. Faced with bare text, an iPhone offers to copy or search it and Google Lens simply runs a web search, so the message is the one thing the reader never sees. Samsung phones and dedicated scanner apps do display it, but a keepsake cannot depend on which phone opens it.

So a message keepsake offers two honest modes. A reveal link encodes a normal URL to a page on this site, with the message itself carried in the URL's fragment — the part after the #. Per RFC 3986, a fragment is stripped before a request is made, so it never reaches our servers, a CDN, or any log; the message is decoded entirely on the reader's device. An offline note writes the words into the code itself, needing no connection ever, and accepts the display caveat above. In both cases the message is also printed on the keepsake, so it can be read by eye regardless.

The fragment format is published here so the codes stay readable by anyone, forever, with or without this site: # then a single flag character (A for UTF-8 bytes, B for raw-deflate compressed bytes), then the payload in unpadded uppercase base32 (RFC 4648), then one base32 checksum character over the payload. Base32 is used rather than base64 because some scanners change the case of what they read, and base32 survives that; it is also a subset of the QR alphanumeric character set, which encodes at 5.5 bits per character instead of 8. Every message keepsake can additionally be downloaded as a self-contained HTML file that decodes this format with no network and no website at all.

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.