signage

README

QR Signage Accessibility Checker

A dependency-free CLI that checks an event QR sign specification before it is printed and installed.

The checker covers scan geometry, contrast, quiet zone, text fallback, plain-language instructions, privacy wording, mounting height, languages, and real-device testing. It is useful for weddings, conferences, venues, exhibitions, and private events.

Quick start

node ./bin/check-signage.mjs ./examples/table-card.json

Machine-readable output:

node ./bin/check-signage.mjs ./examples/table-card.json --json

Blocking findings return exit code 1; invalid input or CLI usage returns 2.

Sign specification

{
  "name": "Reception table card",
  "qrWidthMm": 35,
  "scanDistanceMm": 300,
  "quietZoneModules": 4,
  "contrastRatio": 8.2,
  "shortUrl": "https://example.com/a-b",
  "instruction": "Scan to add photos to the private event album.",
  "privacySummary": "The hosts receive uploads and approve items before display.",
  "mountingHeightMm": 1050,
  "languages": ["en", "de"],
  "testedDevices": ["iPhone Safari", "Android Chrome"]
}

Rules

• QR width must be at least one tenth of the expected scan distance.
• The quiet zone must contain at least four modules.
• Contrast should meet a 4.5:1 threshold.
• A valid HTTPS short URL must be printed as a fallback.
• Instructions must describe the action in plain language.
• Privacy wording must identify the audience or visibility behavior.
• Typical reachable mounting height is checked against a configurable field range.
• At least one language and two real test-device paths are expected.

The geometric rule is intentionally conservative. Camera quality, printing, error correction, lighting, surface reflections, and code density still require a physical field test.

Example output

QR signage readiness: 95/100

Warnings:
  - testedDevices: Test with at least two distinct camera/browser paths.

Result: READY WITH WARNINGS

Why use a machine-readable sign spec?

Print files often lose the operational decisions behind them. A designer sees a square code, while a venue coordinator needs to know the final scan distance, fallback URL, privacy promise, language set, and test record. A small JSON file keeps those assumptions reviewable and versionable.

This project is platform-neutral. For a practical implementation walkthrough, see Gathmo's wedding QR photo setup guide.

Development

The same rules are available as a small Go package:

result := signage.Validate(spec)
if !result.Ready {
	log.Fatal(result.Errors)
}

npm test
npm run check
go test ./...

Node.js 20 or newer is recommended. No runtime dependencies are required.

License

MIT

Documentation

Overview

Package signage validates event QR sign specifications before printing.

Index

• type Finding
• type Result
  • func Validate(spec Spec) Result
• type Spec

Types

type Finding

type Finding struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

Finding describes one validation error or warning.

type Result

type Result struct {
	Score    int       `json:"score"`
	Errors   []Finding `json:"errors"`
	Warnings []Finding `json:"warnings"`
	Ready    bool      `json:"ready"`
}

Result is the scored validation outcome.

func Validate

func Validate(spec Spec) Result

Validate evaluates one sign specification.

type Spec

type Spec struct {
	Name             string   `json:"name"`
	QRWidthMM        float64  `json:"qrWidthMm"`
	ScanDistanceMM   float64  `json:"scanDistanceMm"`
	QuietZoneModules int      `json:"quietZoneModules"`
	ContrastRatio    float64  `json:"contrastRatio"`
	ShortURL         string   `json:"shortUrl"`
	Instruction      string   `json:"instruction"`
	PrivacySummary   string   `json:"privacySummary"`
	MountingHeightMM float64  `json:"mountingHeightMm"`
	Languages        []string `json:"languages"`
	TestedDevices    []string `json:"testedDevices"`
}

Spec records the physical and guest-facing properties of a QR sign.