Store colors on a QR code — with a contrast check

Until now, colors applied to a single download only: ?fg=1F4E79 on the image URL. Now a code can remember its colors.

What is new

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance": {"foreground_color": "#1F4E79"}}'

• Stored: foreground_color and background_color (#RRGGBB, the background also transparent). SVG and PNG draw them from now on without any parameter; PDF and EPS follow with one of the next releases.
• Parameters take precedence: ?fg=000000 still returns the black print file of the same code.
• Error correction stays a per-download choice (?ecc=) and is never stored on the code.

The contrast check

The API checks every color pair before it stores it:

• Below 1.5:1 — white on white, for example — it refuses with 422.
• Borderline pairs are stored and reported as a warning or as critical, for example the brand orange #F7901E on white.
• A transparent background is always critical but never blocked: a light code on dark packaging is allowed. The surface then has to provide the contrast and keep a quiet zone of 4 modules free on every side.

What you need to do

Nothing. Without stored colors every code returns the same bytes as before. The MCP server and the TypeScript SDK from version 1.2.0 know the new fields (npm install @qr3/sdk@latest); the color picker in the dashboard follows.

If you embed an image: an image URL follows the stored colors wherever it does not set them itself with fg and bg. After a color change, a page that embeds such a URL can still show the old image: for up to 24 hours if the URL returned the standard image until then (black on white, error correction M, no logo), for example before the first coloring, otherwise for up to 5 minutes. A parameter of your own such as ?v=2 helps right away.

All details: Store colors on the code.