1. Why Write This Now
TokiQR was born as a personal tool for encoding audio, images, and text into a single QR code. Codec2 for audio compression, Brotli for text compression, fully offline operation. Technically, it runs entirely in the browser. No data is sent to a server. It works even when the network is down.
Then inquiries began arriving from public facilities and libraries. "Could this be used for audio guides?" "Can we embed exhibit descriptions in QR codes?" These were not questions about functionality. What they were really asking was: "Can we trust this?"
The transition from a personal tool to a public tool is not a feature expansion. It is the work of closing a trust gap. This essay records what that gap consisted of and how it was closed.
2. If It Costs Money, We Need an Explanation — Transparent Billing
TokiQR's bulk mode — the feature for generating multiple QR codes at once — consumes multi-QR credits. For a public facility administrator, credit consumption becomes a matter for budget approval. The original UI could not answer the question: "Can we know the cost in advance?"
The fix was straightforward. The generation process was split into two stages. First, display an estimate. Show exactly how many QR codes will be generated and how many credits will be consumed. The user reviews the estimate, then chooses to proceed or cancel.
"You can cancel after viewing the estimate" — this is the minimum condition for an administrator who must explain the process to a supervisor. Technically, it was a few lines of code. But for public adoption, this single step determines whether deployment happens or not.
Billing transparency is not a technical problem. It is about embedding accountability into the structure.
3. The Assurance That You Can Start for Free
The first barrier a public facility administrator faces is not the budget itself. It is the assumption that "you cannot try without a budget."
In TokiQR, encoding short audio into a single QR code requires no credits. Even in bulk mode, single-chunk processing incurs no cost. The fact that "you can start with zero budget" simply exists.
This fact is decisively important in the early stages of adoption. Whether an administrator can tell their supervisor "we can try it for free first" determines whether the tool even makes it onto the table for consideration.
Rather than adding features, lowering the threshold of entry. That is the first step toward public adoption.
4. Testing for Real-World Deployment
Working on a developer's machine and working in the field are different things. When preparing for public facility deployment, four conditions needed verification.
- Offline operation: After the initial access, does the Service Worker cache enable the tool to function without a network? This assumes unstable Wi-Fi within the facility.
- Initial load on slow connections: Before the Service Worker registers on first access, does the page load on slow mobile connections? If the wait is too long, users abandon the tool.
- Camera performance on older smartphones: Can the generated QR codes be read by cameras on devices from three or five years ago? Public facility users do not necessarily carry the latest hardware.
- Print quality of QR codes: Even if a QR code reads fine on screen, does it maintain sufficient resolution when printed? Will reflections from exhibit panel lighting prevent scanning?
These are requirements that never appear in a specification document. But if the tool does not work in the field, no specification matters. Public readiness means guaranteeing operation in the user's real environment, not the developer's ideal one.
5. Structurally Preventing Four Anxieties
When a public facility administrator operates the tool, psychological anxiety — not technical failure — becomes the barrier. Observation revealed four specific anxieties.
"Will this ever finish?" — Uncertainty about completion
Audio encoding takes time. Without a progress bar, users cannot tell whether processing is ongoing or frozen. An Opus encoding progress bar was added, displaying elapsed and remaining time. Simply knowing "it will finish in X seconds" eliminates the anxiety.
"Is it broken?" — Distrust from unresponsiveness
When buttons remain clickable during processing, users suspect malfunction when nothing happens. Buttons are now disabled during processing with loading indicators. Settings UI is locked during estimate display. The "unclickable" state itself communicates "processing in progress."
"Do I have to start over?" — Fear of mistakes
If settings are changed after an estimate is displayed, the estimate becomes invalid. Users worry: "Did I just ruin everything?" Settings UI is now locked during estimate display; modification requires explicit cancellation. By structurally eliminating the possibility of accidental changes, the fear of starting over is severed.
What "structurally prevent" means
Not individual bug fixes, but state transition design that eliminates anxiety. If a button is enabled, it is appropriate to press. If a button is disabled, it is time to wait. The UI state itself becomes the instruction. That is what "structurally prevent" means.
Anxiety is not a bug. It is a target for elimination through state design.
6. Interested but Afraid to Touch — Crossing the Threshold Together
Even after explaining features and improving the UI, one wall remains: "What if I break something?"
Public facility administrators are not IT specialists. Even when a tool is praised as "easy to use," they may be unable to take the first step. Handing over a manual does not move their hands.
The solution was not functional but experiential. Perform the first QR code generation together. Sit beside the administrator, look at the same screen, operate together. Demonstrate that mistakes can be undone. Share the success experience.
"Doing it together" is not technical support — it is accompaniment across a psychological barrier. Once they succeed once, the second time they can do it alone. Being there for just the first time. That is the essence of onboarding support.
7. When There Are Zero Adoption Cases, Walk the User Journey Together
With zero adoption cases, the administrator stands alone. When asked "who else is using this?", the only honest answer is "no one yet." There is no safety net of precedent.
What the developer can do is walk the user journey alongside the adoption coordinator. From reception to guidance, from QR code scanning to audio playback — experience the full flow in the actual facility with actual devices.
This shared experience turns zero into one. Not a case study from another facility, but a success story in their own. Not the reassurance of having a developer nearby, but the fact that "it worked in our facility." The leap from zero to one happens not through features, but through shared experience.
8. Summary — Public Trust Means Naming the Anxiety
Preparing for public deployment is not about adding features. It is about reducing anxiety.
- Split billing into two stages with estimates and cancellation — remove financial anxiety.
- Maintain a free entry point — remove budget anxiety.
- Use UI state transitions to indicate correct actions — remove operational anxiety.
- Experience the first session together — remove isolation anxiety.
When a personal tool becomes a public tool, the amount of code change is modest. What changes is the resolution with which you perceive anxiety. Who fears what, and why. Name it, then structurally eliminate it.
Public trust is born not from the completeness of features, but from the absence of anxiety. Name the anxiety, sever it with structure. That is the condition for a personal tool to open itself to the public.