Guides

The generators on this site make keepsakes; these 8 guides explain the rules they work to. Every rule in the rendering engine exists because its limit was measured with a real decoder; the methodology page states them in one place. The guides take them one at a time: which parts of a code are never decorated and why, what each style spends its decode margin on, how a render earns the "Verified scannable" badge, and what a message keepsake can and cannot do once a phone reads it.

Every engine figure in every guide — each limit and each worked result — is read from the engine at build time, so a guide cannot quietly disagree with the tool. A few of the engine's fixed points recur throughout: the 4-module quiet zone that is always drawn; level-H error correction, roughly 30% recovery, for every style that redraws modules — hearts and the photo halftone — with a framed code without heart modules allowed to opt in to level Q; the 4.5:1 contrast gate; and the 2-of-3 decode rule. Of the 10 presets behind the occasion pages, 7 start on a frame, 2 on the Heart modules style and 1 on the Photo-woven style.

Why decorated QR codes still scan

The anatomy rule. A scanner locks onto the three large corner squares and orients a dense symbol by its smaller alignment squares, and restyling alignment patterns broke decoding outright in testing — so finder and alignment patterns are classic crisp squares in every style, timing tracks may be styled, and the 4-module quiet zone is never covered by frame art. The guide classifies the modules of several occasion examples by zone and shows why the styles that redraw modules encode at level H.

Heart-module codes, explained

Dark modules redrawn as hearts spanning 0.97 of their cell — large enough that a scanner's sampling grid still reads each cell as decisively dark. Foreground and background must measure at least 4.5:1 under the WCAG formula, and the engine rejects a weaker pair rather than warning. The guide runs that gate on several colour pairs, accepted and refused, and sets out what a heart code can carry and what it cannot.

Photo halftone codes, explained

How a picture and a code share one surface. Each data cell is split: the centre 50% of the cell stays in pure module colour, because decoders sample near cell centres, and the outer ring shows the photo quantised to three tones at luminance thresholds 85 and 175. Landmark cells and the quiet zone stay pure, no logo may be stacked on a halftone code, and the payload is capped at version 4. The guide gives the character budgets that follow and renders a synthetic photo through the engine.

Framed codes, explained

The one family that decorates nothing inside the code. The rendered symbol, quiet zone included, sits on an opaque panel drawn above the frame art, so decoration cannot touch a module by construction. The 5 templates — heart, floral, ring, classic, confetti — are recolourable vector art, and recolouring changes the frame, never the panel. Because the symbol is untouched, a framed code without heart modules may also carry level Q when the smaller-code setting is chosen; the engine rejects anything below Q. The guide measures a framed example's geometry, explains the caption limits, and shows what hearts inside a frame change.

Decode verification: how the badge is earned

After every render your browser rasterises the finished artwork at 3 sizes — 800, 1200, 1600 pixels — runs jsQR on each, and compares the decoded bytes with your exact content. At least 2 of the 3 must match, because a render can fail at exactly one raster size through sampling resonance and decode at the others. Anything less shows a warning and keeps the downloads locked. The guide executes that loop on real renders when the page is built and sets out what the badge cannot promise.

Message keepsakes and reveal links

A code containing bare text carries no scheme, so a phone has nothing to act on: an iPhone offers to copy or search it, and Google Lens runs a web search. A reveal link instead encodes a URL to this site with the message in the fragment, which is stripped before any request is made and never reaches a server, a CDN or a log; an offline note writes the words into the code and accepts that caveat. The guide works the fragment format through on an original message — flag A or B, base32 payload, checksum character — against the 300-character limit, and covers the self-contained HTML download.

Printing and scanning a keepsake

Verification proves the artwork decodes at screen resolution; it cannot see your printer, your paper or the phone that will do the scanning. The guidance is short: 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. The engine adds a floor of 0.5 mm per module for the code you made, and flags a symbol past 65 modules across as oversized. The guide works the PNG presets through at 300 DPI — 512 px prints at 43.3 mm; 1024 px prints at 86.7 mm; 2048 px prints at 173.4 mm — and why a photo-woven code prints larger.

Treasure-hunt chains

The one occasion that is plural. The chain module turns a pasted list of clues — one per line, blank lines ignored — into a numbered chain of between 2 and 20 cards, each captioned with its position and the final card marked as the prize. Rendering and verification are unchanged, so every card earns its badge individually. The guide builds a fictional chain at build time and shows what each card's code carries.

Where the rules are applied

Each occasion page applies these rules to one preset, with figures computed from its own fictional example: Proposal, Wedding, Baby reveal, Gender reveal, Valentine, Gift tag, Treasure hunt, Memorial, Pet tag and Photo keepsake. The full rule set is on the methodology page; the about page sets out what the site is for and its honest limits.

Every render is decode-verified in your browser before it can be downloaded. The measured rules each guide explains are collected on the methodology page; the occasion pages apply them one preset at a time.