| name | qr-labels |
| description | Print a label carrying a QR code — what to encode, how big it has to be to scan, and how it shares the label with text. |
QR labels
A QR label is a normal label with --qr. What makes it its own skill is that a
QR can be printed perfectly and still be useless, and neither the printer nor the
render will tell you.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render.py" preview \
--text "A-100" --subtext "Instant Pot" \
--qr "https://inventory.example/a/100" --printer ql-810w -o /tmp/label.png
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/render.py" print \
--text "A-100" --subtext "Instant Pot" \
--qr "https://inventory.example/a/100" --printer ql-810w
The QR sits square on the left, sized to the media height; text takes the rest.
On die-cut media it is capped at 45% of the label length so it cannot squeeze the
text into a sliver.
What to encode
- A URL that will still resolve. The point of a QR on a physical object is
that someone scans it in two years. A link to a local dev server, a session
URL, or anything with a token in it is worth flagging before printing.
- Short beats long. QR density rises with payload; a long URL on 12 mm tape
produces a code too fine for the print head to resolve. Prefer a short
canonical link over a tracking-laden one.
- Plain text is valid too — a serial number, a wifi credential, a phone
number. It does not have to be a URL.
Whether it will actually scan
Three things decide this, and only the first is visible in the preview:
- Module size. The renderer sizes the QR to the media height, so narrow
tape means a physically small code. On 12 mm tape a long URL will not scan
reliably no matter how clean the print.
- Print resolution. DK media prints at 300 dpi, TZe at 180. The same QR is
coarser on tape.
- Contrast and material. Clear and matte-silver stock scans worse than
white paper.
The renderer uses error-correction level M, which tolerates roughly 15% damage —
a reasonable default for a label that will get scuffed. It does not compensate
for a code that is simply too small.
Scan the first one before printing the batch. This is the whole judgement of
this skill: a QR label is verified by a phone camera, not by looking at it. If
the user is about to print twenty, print one, ask them to scan it, then print the
rest.
Combining with text
Always put something human-readable on the label as well. A QR-only label is
unidentifiable when the code will not scan, which is exactly when you need to
know what it was.
--text is the large line — the id, the thing you read across a room.--subtext is the small line — the name, dropped automatically below ~18 mm.
Generating a QR on its own
Occasionally the user wants the code as an image rather than a label — for a
document, a sign, a slide:
qrencode -o /tmp/qr.png -s 10 -m 1 "https://example.com/thing"
-s is pixels per module, -m the quiet-zone margin in modules. Keep -m at 1
or more; a QR with no quiet zone fails to scan against a busy background even
though it looks fine.
Judgement
- Ask before printing a placeholder URL.
example.com, localhost, an
unresolved template variable — these produce a label that must be redone.
- One object, one code. If the user is labelling several things, each needs
its own URL; printing copies of one QR onto different objects defeats the
purpose. Check which they meant before printing copies.
- If the payload is long and the tape is narrow, say so before printing rather
than after — suggest a shorter URL or wider media.
