Skip to content

feat: add QR code customisation (colours, shapes, corner squares, logo) - #24

Merged
Deityhub merged 4 commits into
mainfrom
feat/qr-customisation
Nov 12, 2026
Merged

Deityhub merged 4 commits into
mainfrom
feat/qr-customisation

Conversation

@Deityhub

@Deityhub Deityhub commented Nov 12, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds customisation to the package and the demo site: colours, gradients, module shapes, styled corner squares and a logo in the middle, with built-in scan-safety checks. Everything stays dependency-free, and generateQRCode / renderToSVG / renderToPng are unchanged for existing callers.

Library

  • generateQRSymbol(config) returns { matrix, version, ecl, mode, quietZone, modules } (generateQRCode is now generateQRSymbol(config).matrix)
  • renderToStyledSVG(symbol, style): solid colours, linear/radial gradients, transparent background, rounded background corners, module shapes (square, rounded, dots, diamond) with a size setting, corner frame/dot shapes and colours, optional logo (square or circle, size, margin, backing colour)
  • analyzeStyle(symbol, style) returns { warnings, errors, logoCoverage, contrastRatio } (low contrast, inverted colours, transparent background, small modules)
  • Logo safety: only error level Q or H, and the hidden area is capped (12% at Q, 15% at H); strict: false turns the errors into warnings. A logo can never cover a corner square, format or version information
  • Alignment patterns are always drawn as solid squares: scanners use them to find the grid, and without this every shaped style failed jsQR on codes of version 2 and up
  • renderToPng(matrix, size, { foreground, background }) writes a 2-colour palette PNG (with transparency); renderSvgToPng(svg, size) makes a PNG from a styled SVG in browsers (in Node, convert the SVG with sharp or resvg, documented in the README)
  • Colours (hex, rgb(), hsl(), basic names) and logo hrefs (base64 data:image or https://) are strictly validated and throw StyleError; nothing user-supplied is copied into the SVG unchecked. Tests include hostile strings

Demo site

  • Style / Logo / Options tabs with presets (real mini QR thumbnails), colour swatches, gradient, shape pickers, custom corner colours, logo upload (stays in the browser), live scan-safety warnings, and a one-click "Use level H"
  • Preview is sticky beside the settings on desktop and a compact bar pinned at the top on phones and tablets; download size sits next to the download buttons
  • Fixes found along the way: overflow: hidden on the shell silently broke position: sticky (now overflow: clip); presets no longer reset the logo settings and logo changes no longer deselect the preset
  • README documents all of the above and has new desktop and phone screenshots; FAQ and JSON-LD mention customisation

Verification

  • 124 tests (the original 81 plus style and PNG tests), npm run lint, npm run build and npm run test:package pass
  • Decoder campaign: 408 styled codes rendered in headless Chrome and read with jsQR and zxing. Every shaped style decodes (the only misses are the ones the warnings cover: low-contrast gradients and inverted colours). Every logo combination the library allows decodes (140/140); failures only start at about 21% coverage on Q and 29% on H, well above the caps. A logo at the cap costs nothing under random damage compared with a plain code
  • Styled PNGs exported by the real browser path (gradient, dots + logo, transparent) decode with both scanners; the maximum-size logo screenshot code reads with both
  • Demo checked at 320, 360, 768 and 1280 px in every tab and state: no overflow and no clipped button text

Notes

  • UMD bundle grows by about 13.6 KB (about 115 KB to about 128.5 KB)
  • Not tested with physical phone cameras; shapes with gaps (dots, diamond, scale below 1) are read by most scanners but not all, so the README recommends scanning before printing
  • Merging this (a feat:) will make release-please propose a minor release

Brand, social image and SEO (added later)

  • New app icon in the demo's own blue (#0e7bf7 to #0d63c4) and a full favicon set: favicon.svg, favicon.ico (16/32/48 px), a 96 px PNG, apple-touch-icon.png, 192/512 px icons and site.webmanifest; the old inline data: favicon is gone (Google cannot use it in search results)
  • New og.png about the customisable QR code: three real styles, all encoding https://qr.deityhub.com/, with the app icon as the logo in the main code (each code was scanned with jsQR and zxing)
  • Title and description mention the customisation; robots meta allows large previews and snippets; og:locale and image alt text added
  • JSON-LD: WebSite, Person (same @id as judeojini.com, so both sites describe one entity), WebApplication with a feature list, the library as SoftwareSourceCode, HowTo and an 8-question FAQPage. The structured data text is generated from the same source as the visible intro, features, steps and FAQ and was checked to match word for word
  • llms.txt for AI tools, dated sitemap.xml, cache headers for the new files

After deploying: submit https://qr.deityhub.com/sitemap.xml in Google Search Console and refresh the social image caches (Facebook Sharing Debugger, LinkedIn Post Inspector).

- generateQRSymbol returns the matrix with the version, level, mode and
  quiet zone used; generateQRCode delegates to it
- renderToStyledSVG draws custom colours, linear/radial gradients,
  square/rounded/dots/diamond modules, styled corner squares, rounded
  background corners and a logo; alignment patterns are always solid
  squares so scanners can find the grid
- analyzeStyle reports contrast, inverted colours, transparent background
  and small module problems, and the logo coverage; a logo needs level Q
  or H and is capped by hidden area (12% at Q, 15% at H)
- Colours and logo URLs are strictly validated (StyleError), nothing
  user-supplied reaches the SVG unchecked
- renderToPng accepts foreground/background colours (palette PNG, with
  transparency); renderSvgToPng turns a styled SVG into a PNG in browsers
- Tests cover shapes, gradients, validation, hostile input, the logo
  limits and the PNG chunks
- Demo: Style / Logo / Options tabs with presets, colour swatches,
  gradient, shape pickers, corner colours and a logo upload; live
  scan-safety warnings; compact preview pinned above the settings on
  phones and sticky beside them on desktop; download size next to the
  download buttons
- Fix the page shell clipping so position: sticky works
- Presets keep the logo settings, and logo changes keep the preset
- README: document generateQRSymbol, renderToStyledSVG, analyzeStyle,
  logos, PNG options and scan-safety guidance; desktop and phone
  screenshots
- App icon in the demo's own blue (#0e7bf7 to #0d63c4): favicon.svg,
  favicon.ico (16, 32, 48 px), a 96 px PNG (Google wants multiples of
  48), apple-touch-icon, 192 and 512 px icons and a web manifest
- New og.png about the customisable QR code: three real styles, all
  encoding https://qr.deityhub.com/, with the app icon as the logo in the
  main code
- Cache headers for the new files and the manifest content type
- Title and description now mention the customisation, plus robots meta
  (large previews and snippets), og:locale and image alt text
- Link the new favicon set and manifest instead of an inline data URI
- JSON-LD: WebSite, Person (the same @id as judeojini.com so both sites
  describe one entity), WebApplication with a feature list, the library as
  SoftwareSourceCode, HowTo and an 8 question FAQPage
- Visible intro, features, how-to steps and FAQ that match the structured
  data exactly
- llms.txt for AI tools and a dated sitemap
@Deityhub
Deityhub merged commit 71faf0a into main Nov 12, 2026
3 checks passed
@Deityhub
Deityhub deleted the feat/qr-customisation branch November 12, 2026 23:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant