The Label a Camera Has to Read
An asset label has two readers. One is a person who will complain when it looks wrong, and one is a camera that will simply fail. We shipped a barcode that was invisible in dark mode and perfect in every screenshot, which is exactly the failure a machine reader produces.
Every asset in this product can be printed with a scannable label, and scanning one is how a movement gets recorded in the field rather than remembered until later. The interesting engineering in that sentence is not the barcode. It is that the label has to be correct for a reader who cannot tell you it is wrong.
The rule that came out of this
A machine-readable code does not follow a theme in either direction. Dark ink on a light plate, always, in light mode and dark mode alike — because every scanner ever built expects it, and because the failure mode of getting it wrong is silence rather than a complaint.
Two symbologies, opposite failures
This product renders two kinds of code, and they behave completely differently when the surface under them changes.
A QR code
- Bakes its own white background rectangle
- Survives any surface it is placed on
- Looks slightly odd on a dark card, and still scans
- Forgiving in the way that hides the problem
A Code 128 barcode
- Is bars on nothing — it draws no background
- Takes the colour of whatever is behind it
- On a dark card: near-black bars on dark slate
- Invisible to a person, unreadable to a scanner
The second one shipped. A card whose background became theme-aware left the barcode drawn on it with nothing behind it, and in dark mode the code disappeared into the surface. It was correct in every light-mode screenshot anybody took, which is why it survived review.
A person reports a colour they cannot read. A scanner just does not beep, and the operator concludes the label is damaged.
And then the same mistake, backwards
The obvious fix is to make the ink theme-aware too. That is the second version of the bug and it is easier to write than the first.
Where a plate is already a fixed white — a printed label, a document header — drawing the code in a theme-aware ink colour means the ink goes near-white in dark mode and the code vanishes into the plate. Same outcome, opposite cause, and a fix for one direction that causes the other.
So the plate and the ink are a pair. They are held as three fixed values — plate, ink, and the plate's border — defined identically in every theme block in the stylesheet, which is what makes an automated check see them as deliberate rather than as a colour somebody forgot to convert.
The third trap, which is about paper
The same code partial is included by document templates that are rendered to PDF. The PDF renderer does not resolve CSS custom properties at all — and critically, it does not fall back to the declared fallback value either. It simply drops the declaration.
So a token in that partial does not degrade gracefully to a sensible default. It produces no colour rule at all, on the one output that is most likely to be scanned by a warehouse device and least likely to be looked at on screen before it is printed a thousand times.
That partial keeps literal colour values on purpose, with a comment saying why. It is the one place in the stylesheet where "not tokenised" is the correct answer.
Three ways one barcode fails, and what each looks like
All four look identical in a light-mode screenshot, which is the only review most interface changes receive.
Two, for operations that actually live on scanning
Labelling is built and works. These are the two things a scan-heavy operation asks for once it has been running for a few months.
Label templates matched to your stock
Physical label sizes, fixed-asset plate layouts, and the field selection that goes on each — so a label prints to the media you already buy rather than to a page you then cut up. Small, specific, and the kind of thing that is only worth doing against a real label you send us.
A scan-first movement flow on a handheld
Scan, choose the action, done — rather than navigate, search, then scan. The movement actions and the codes both exist; what would be built is the shortest path between them for someone holding a device and a box at the same time.
How it works: you describe the requirement, we return a written scope, timeline and cost, and once agreed it is built into your environment and maintained as part of the product. For label work, send an actual label — the specification is physical and a description of it is never enough.
Talk to us about labelling and scanningFour questions about codes and labels
Show me a printed label, on paper.
A good answer sounds like
They print one.
What it actually means
The screen version and the paper version go through different renderers. Ours differ in whether custom properties resolve at all.
Which symbology, and why that one?
A good answer sounds like
A named answer tied to the reader.
What it actually means
A linear code and a QR fail in opposite ways on a coloured surface, and a vendor who has not thought about it has probably not tested it.
Does the code change appearance with the interface theme?
A good answer sounds like
No, never.
What it actually means
A yes is a bug that will be reported as damaged labels rather than as a display defect.
What does the code encode — the tag, or an internal id?
A good answer sounds like
The tag a human can also read.
What it actually means
A code encoding an internal identifier is unreadable by a person when the scan fails, which is exactly when you need to read it.
What AWRA OpsHub does today
- Printable labels for assets carrying a scannable code, generated in the product rather than by an external service.
- Both a linear barcode and a QR code, rendered as vectors so they survive scaling.
- A theme-fixed plate and ink for every machine-readable code, defined identically across all four theme blocks so an automated check sees them as deliberate.
- Literal colours retained in the code partial used by the PDF templates, deliberately and with the reason recorded in the file.
What it does not do
- Configurable label templates or physical media sizes.
- A scan-first handheld flow. Scanning works within the normal screens; there is no dedicated device path.
- Any check that a printed label actually scans, other than somebody trying it.
- Label reprint tracking — nothing records that a tag was reissued.
Not ours, by choice
- The dark-mode barcode was a real defect that shipped, and it was invisible in every screenshot taken during review. We are describing it because the failure mode generalises well beyond us.
- The three fixed colour values are an exception to a house rule that everything else on the dashboard follows the theme. Exceptions that are not written down get "fixed" by the next person.
- Nothing here is Japanese. Japan is here as a market where operational scanning discipline is mature enough that a label which fails intermittently is noticed and reported precisely.
Print one and scan it
Of every test in an evaluation, this is the cheapest and the one most likely to find something: print a label from the real system, on real paper, and scan it with the device you will actually use.
Talk about asset labellingFrequently asked questions
Why not just use QR codes everywhere?
They are more forgiving, which is a genuine argument. Linear codes remain because a lot of existing warehouse hardware reads them faster and because a narrow label sometimes cannot fit a square. The right answer is to know which one you are printing and why.
Does the code work in the mobile app?
Scanning to find a record works. What is not built is a dedicated scan-first flow where the scan itself chooses the action, which is the difference between usable and fast for someone doing it a hundred times a day.
How was the dark-mode barcode found?
By an automated check that resolves every colour token to its dark-mode value and measures the contrast of text against the ground behind it. It is gated at zero findings rather than ratcheted, because a measurably unreadable result has no defensible allowance.
