Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Components

QR code

A QR code as a picture with its words beside it: a UPI link, a ticket number, a Wi-Fi password. The encoder is in the component (numeric, alphanumeric and UTF-8 byte modes, versions 1 to 40, levels L to H, all eight masks) with no dependency, tested against the standard's example, a reference encoder and a decoder.

quiet warm playful for payment, qr, ticket, upi, wifi

Open the live demo npx @susegad/cli add qr

Stands on: Core, Core: components, Engine, Tokens

The prompt

the prompt

The code on a payment slip, a ticket or a guest-room card: a picture a phone can read, with the same words printed beside it for people.

A QR code drawn as an SVG from an encoder written for it, with the words it carries kept beside it as ordinary text. Quiet is a white plate; warm is a paper plate with a hand-ruled frame; playful adds block-print studs and draws the frame on once.

<link rel="stylesheet" href="susegad/components/qr/qr.css">
<script type="module" src="susegad/components/qr/qr.js"></script>

<sg-qr value="upi://pay?pa=casaexemplo@okaxis&pn=Casa%20Exemplo&am=25500.00&cu=INR" ecc="M"
       label="QR code for the UPI payment link">
  <p>Pay Casa Exemplo <strong>₹25,500</strong></p>
</sg-qr>

The prompt

Make a web component that shows a QR code as an image, with its text beside it, such as a UPI payment link, a ticket number or a Wi-Fi password. Write the encoder yourself as a pure module with no dependency, and test it in Node against known vectors. Choose the cheapest mode: digits only is numeric, capitals and a few symbols is alphanumeric, anything else is byte mode with the text as UTF-8, so the rupee sign and Devanagari work. Choose the smallest version, 1 to 40, that holds the text at the error-correction level the builder asks for (L, M, Q or H). Split the data into the standard's blocks, add Reed-Solomon error correction over the finite field with 256 elements, interleave the blocks, lay the bits out in the zigzag, then try all eight masks, score each with the four penalty rules and keep the lowest. Write the format and version information. Return the matrix as plain rows of 0 and 1, and a function that turns it into one SVG path of horizontal runs with a four-module quiet zone. Draw it as an SVG with shape-rendering="crispEdges" and role="img", named by a label attribute. Keep the builder's own words as real text beside it: selectable, wrapping on a phone (below the code when there is no room beside it), breaking even a long link with no spaces. If there is no value attribute, the words are the value. Always draw the code dark on a light plate, even in dark mode and in forced colours, because a code that is light on dark does not scan. Three registers: quiet is a plain plate with a hairline; warm is a paper-coloured plate with a hand-ruled frame in a margin around the code, a thick rule and a thin one, wobbling a little from a seed; playful adds a diamond stud on each corner and in the middle of each side and draws the frame on once when first seen. The frame never touches the code's quiet zone and the modules never change in any register. With reduced motion, show the finished frame. If the text will not fit in any code, keep the words, drop the picture, set data-error and fire an event with a plain message. Without JavaScript the words still show.

Words to code

When you sayTechniqueWhat happens
a pure module … tested against known vectorspure coreqr.core.js has no DOM and no import beyond the seeded rng. Its tests check the ISO/IEC 18004 Annex example's codewords, 14 matrices and a hash of every version at every level from a reference encoder (Project Nayuki's), and a decode round trip through jsQR.
the cheapest modemode choicemodeOf(text): digits only is numeric, the 45-character set is alphanumeric, anything else is byte.
UTF-8byte modeTextEncoder turns the text into bytes; the rupee sign is 3 bytes, a Devanagari letter 3.
the smallest version that holds itcapacityencode raises the version from 1 until the header and the data bits fit the data codewords for that level; past 40 it throws a RangeError that says how much fits.
Reed-Solomon over the field with 256 elementsGF(256)Log and antilog tables for polynomial 0x11D; generator(n) builds the divisor and remainder divides the data by it.
interleave the blocksblocksShort blocks first, then longer ones with one more data byte; data taken column by column, then error correction column by column.
try all eight masks and keep the lowest penaltypenaltypenalty() scores runs of five or more, 2 by 2 blocks, the 1:1:3:1:1 finder shape with light on a side, and dark proportion. The first lowest mask wins, as in the reference.
one SVG path of horizontal runspathDatapathData(rows) writes M x y h n v1 h-n z for each run of dark modules, offset by the quiet zone, so the whole code is one <path>.
always dark on a light platescanning--sg-qr-light and --sg-qr-dark are constants, not theme tokens; the plate and the SVG set forced-color-adjust: none.
the words are the valuetextWith no value, .value is the element's collapsed text, and a MutationObserver redraws when it changes.
a hand-ruled frameseedframePaths(seed) jitters the corners and bows each side of two rectangles, from the value, so the same code always gets the same frame.
draws the frame on oncerevealreveal(motion) is non-null only in full motion; the rules animate stroke-dashoffset (with pathLength="1") and the studs fade in. The animations are cancelled when they end.
a plain messageerrorsg-qr-error carries the core's RangeError text.
never so small it will not scansize floorThe element sets --sg-qr-units (modules plus quiet zone) and the CSS holds the plate to min-width: units × 2px ÷ fill + 2px, where fill is 1 in quiet and 0.86 in warm and playful, whose frame margin is a percentage margin on the picture. minPlate() in qr.helpers.js is the same sum, tested.
a link a payment app will acceptchecked payloadupiPayload requires handle@bank, an amount of at most two decimals (numbers rounded, no float noise), INR, and a note of 80 characters or fewer, and throws a plain TypeError otherwise. wifiPayload takes WPA (WPA2 and WPA3 too), WEP or nopass.

Accessibility

  • The picture is one role="img" named by label. The words beside it are text.
  • The frame and studs are aria-hidden; nothing takes focus.
  • The plate is light in every theme and in forced colours, with at least 10:1 between modules and ground.

Credit

The encoder follows ISO/IEC 18004; its tests compare it with Project Nayuki's QR Code generator library (MIT) and jsQR. The studs are the diamond cuts of Indian block printing. Tier: pan-Indian.

<sg-qr> draws a QR code as a picture and keeps the words beside it as real text: a UPI link, a ticket number, a Wi-Fi password. The encoder is part of the component, written from the standard, with no dependency, so it works on a page with no network.

Use

<link rel="stylesheet" href="susegad/components/qr/qr.css">
<script type="module" src="susegad/components/qr/qr.js"></script>

<sg-qr value="upi://pay?pa=casaexemplo@okaxis&pn=Casa%20Exemplo&am=25500.00&cu=INR"
       label="QR code for the UPI payment link">
  <p>Pay Casa Exemplo <strong>₹25,500</strong></p>
  <p>Or pay to <code>casaexemplo@okaxis</code>.</p>
</sg-qr>

The element's own markup is the text beside the code. It is the real content: the picture only repeats it for a phone camera, and it is what a screen reader reads and what people select and copy. Without JavaScript the text shows and the picture does not.

When there is no value, the element's text is also what the code says:

<sg-qr label="QR code for the ticket number">TICKET-GOA-2026-0001234</sg-qr>

Building the value

qr.helpers.js has two helpers for what people usually put in a code. They check what you give them and throw a TypeError in plain words, so a bad amount fails on your page instead of in a payer's app:

import { upiPayload, wifiPayload } from './qr.helpers.js';

upiPayload({ pa: 'casaexemplo@okaxis', pn: 'Casa Exemplo', am: '25500.00', tn: 'Booking 12 to 15 Oct' });
// upi://pay?pa=casaexemplo@okaxis&pn=Casa%20Exemplo&am=25500.00&cu=INR&tn=Booking%2012%20to%2015%20Oct

wifiPayload({ ssid: 'Casa Exemplo guests', password: 'susegad-2026' });
// WIFI:T:WPA;S:Casa Exemplo guests;P:susegad-2026;;

What the helpers accept:

FieldRule
pathe payee's UPI address, handle@bank, no spaces
ama positive amount in rupees. A number is rounded to two places (0.1 + 0.2 gives 0.30). A string must already be a plain decimal with at most two places; '1e3', '-5' and '12.345' are refused, not guessed at. Written as 2500.00
cuINR in any case; anything else is refused
tnthe note, 80 characters at most. That cap is ours: we did not have the NPCI linking spec to check, and some apps show less
trthe transaction reference; merchant payments need one
security (Wi-Fi)WPA (WPA2 and WPA3 are written as WPA, which is what phones read), WEP or nopass; anything else is refused

Attributes

AttributeValuesDefault
valueany text, up to 2,953 bytes at level Lthe element's own text
eccL, M, Q, H: about 7, 15, 25 and 30 percent of the code can be damaged or covered and still readM
labelthe picture's accessible nameQR code
sizethe plate's width: a number is px, or a length such as 12rem12rem
registerquiet, warm, playfulinherited

Choose ecc by where the code will live: L on a screen, M on paper, Q or H on something that will get scuffed. Higher levels make a bigger code.

Properties and events

  • symbol (read only): the last matrix drawn, { version, size, ecc, mode, mask, rows }, or null. rows[y][x] is '1' for a dark module.
  • sg-qr event, bubbling, detail: { version, ecc, mode, size }, each time the picture is drawn.
  • sg-qr-error event, detail: { message }, when the value will not fit. The picture is dropped, the words stay, and the element gets data-error.
  • Changing value, ecc, label or size, or editing the text when there is no value, redraws.

Registers

LookMotion
quieta plain white plate with a hairlinenone
warma soft paper plate with a hand-ruled double frame in its paddingnone
playfulas warm, with block-print studs on the corners and the middle of each sidethe frame draws itself on once, when first seen

The modules are the same in all three registers: same shape, same size, dark on light. Only the plate's margin carries the register. Reduced motion shows the finished frame.

Scanning

  • The plate is light in every theme. A QR code is dark modules on a light ground, so the plate does not follow dark mode, and in forced colours it keeps its own colours (and gets an edge in the system text colour).
  • The code keeps the four-module quiet zone the standard asks for, inside the picture. The frame sits outside it.
  • Size floor. A phone reads a code reliably when each module is at least 2 CSS px. The element holds the plate to that, whatever size says: the plate is never narrower than 2 px × (modules + 8) + 3 px in quiet, and 2 px × (modules + 8) ÷ 0.86 + 3 px in warm and playful, whose frame margin takes 14% of the width. A UPI link (usually 41 modules, version 6) comes to 101 px in quiet and 117 px in warm and playful; a version 8 code with Indian-script text (49 modules) to 117 and 136 px. On a narrow screen the plate is also held to the width of its row.
  • The picture is an SVG with shape-rendering="crispEdges", so it stays sharp at any size and prints cleanly. Print the plate at 2 cm or more on a side for a short link.
  • If you change --sg-qr-light or --sg-qr-dark, keep at least 10:1 between them and keep the modules the dark one. Inverted codes (light on dark) do not scan on many phones.

Accessibility

How this component meets WCAG 2.2 level A and AA, criterion by criterion, how each was checked, and what your page still owns.

  • Meets 9
  • Meets with author's part 1
  • Not applicable 1
CriterionStatusHow it was checked
1.1.1 Non-text contentMeetsThe picture is one role="img" named by label, and the words beside it are real text with the same content; the frame and studs are aria-hidden. packages/components/qr/qr.check.mjs: "one role="img" per code, named by its label (and "QR code" when none is given)", "the accessibility tree offers the labelled picture once", and "playful: the frame is aria-hidden, so the tree still holds only the four codes".
1.3.1 Info and relationshipsMeetsThe words are the element's own markup, in the document, and the picture repeats them for a camera. qr.check.mjs: "the words beside the code select as real text, with the UPI address in them" and "without JavaScript the words show, in the demo layout, and there is no picture".
1.4.1 Use of colorMeetsNothing is told by colour: the code is dark modules on a light plate, and what it says is in the words beside it (packages/components/qr/qr.docs.md, "Accessibility"). The registers differ only in the plate's margin.
1.4.3 Contrast (minimum)Meets with author's partThe component sets no colour on the words beside the code: they take the page's text colour on the page's ground, which is the author's. packages/components/qr/qr.check.mjs: "axe, <register>, <theme>: 0 violations" in every register, light and dark, with the frame drawing on, at phone width and with JavaScript off.
1.4.4 Resize textMeetsManual test, 2026-10-07 (throwaway Playwright script): the demo page in quiet, warm and playful, with the root font size at 200 percent at 1280 px wide, and at 320 px wide (plain, and with the WCAG text-spacing values injected: line height 1.5, letter 0.12em, word 0.16em, paragraph 2em); the page was never wider than the screen (document scroll width minus window width was 0 in every case) and no box that hides its overflow had text running out of it. The clipping probe is coarse (it only sees boxes with overflow: hidden).
1.4.10 ReflowMeetsqr.check.mjs: "<width> px: the words wrap below the plate, nothing scrolls sideways, the text stays inside the card" and "a 70-character link with no spaces wraps inside a 320 px screen". The plate is never narrower than the size floor that keeps each module at 2 CSS px (see "Scanning"), and on a narrow screen it is held to the width of its row.
1.4.11 Non-text contrastMeetsqr.check.mjs: "<register> / <theme> / <code>: the modules sit on a light ground, contrast at least 10:1" for every register, theme and code, with a control that a grey-on-grey plate fails it; the plate stays light in dark mode and in forced colours (the check "forced colours ...: the plate keeps dark modules on a light ground and still decodes"). The frame and studs are decoration.
1.4.12 Text spacingMeetsManual test, 2026-10-07 (throwaway Playwright script): the demo page in quiet, warm and playful, with the root font size at 200 percent at 1280 px wide, and at 320 px wide (plain, and with the WCAG text-spacing values injected: line height 1.5, letter 0.12em, word 0.16em, paragraph 2em); the page was never wider than the screen (document scroll width minus window width was 0 in every case) and no box that hides its overflow had text running out of it. The clipping probe is coarse (it only sees boxes with overflow: hidden).
2.2.2 Pause, stop, hideNot applicableNothing runs for more than five seconds. In playful the frame draws itself on once, when first seen, in the calm duration (packages/components/qr/skins/warm.js, shared by playful), and qr.check.mjs asserts "playful, motion allowed: the frame's rules and studs animate once, then none are left running". Quiet and warm: "nothing animates".
2.3.1 Three flashes or below thresholdMeetsThe only movement is the frame's rules drawing on and its studs fading in once, over the calm duration, with nothing repeating (packages/components/qr/skins/warm.js; qr.check.mjs: "playful, motion allowed: ... animate once, then none are left running", "playful, reduced motion: nothing animates at all, and the frame is already whole"). The code itself is static.
4.1.2 Name, role, valueMeetsA role="img" with a name, and nothing to operate. qr.check.mjs: "axe, <register>, <theme>: 0 violations", "axe, playful, dark, phone width: 0 violations", "axe while the frame is drawing on: 0 violations", and "axe without JavaScript: 0 violations".

The page author owns:

  • The label, in the page's language, saying what the code does (the default, "QR code", is English only), and lang on it if it differs from the page (3.1.2).
  • The words beside the code: the link, number or password, so a person who cannot scan has the same information (1.1.1).
  • The colours the page sets behind the words, and any change to --sg-qr-light or --sg-qr-dark (keep at least 10:1 between them, modules dark).
  • Printing the plate large enough for a camera: 2 cm or more on a side for a short link.

How it behaves

  • The picture is one role="img" with label as its name. Say what the code does ("QR code for the UPI payment link"), not what it looks like.
  • The text beside the code is the real content, so a person who cannot scan or see the picture has the same information. Put the link or the number in it.
  • The frame and studs are aria-hidden. Nothing here takes focus: it is an image with text, not a control.
  • The text beside the code wraps, including long links with no spaces, down to a 320 px screen. On a narrow screen it moves below the plate.

All 57 tables, and how the library tests

To do

The default label, "QR code", is English only. Give each code a label in the page's language for now. When the shared strings module (core-strings) lands with the language work, the default will follow the page's lang.

Limits

Byte mode carries UTF-8, so the rupee sign and Devanagari or Kannada text work, but each takes 3 bytes. The code holds at most 2,953 bytes (level L), 2,331 (M), 1,663 (Q) or 1,273 (H), and 7,089 digits. A UPI link fits easily; more than a few hundred bytes makes a dense code that is hard to scan from a phone screen.

Credit

The encoder follows ISO/IEC 18004, and its tests compare it with Project Nayuki's QR Code generator library (MIT) and an independent decoder, jsQR. The frame's studs are the diamond cuts of Indian block printing, shared with the stamp. Tier: pan-Indian.