From 91e986b32c2c1f4820a3e84bf054f8ac7f687308 Mon Sep 17 00:00:00 2001
From: Daniel Bedeleanu <bede@tfm.ro>
Date: Fri, 17 Apr 2026 11:10:10 +0300
Subject: [PATCH] refactor(ux): simplify jargon and improve feature
 discoverability
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addressed P3 design opportunities from critique:

1. Technical Jargon Simplification
   - "Optical Assist" → "Smart Scan" (clearer scanning intent)
   - "Protocol Detected" → "Text Found" (plain language)
   - "OCR Matching Key" → "Item ID or Code" (concrete terminology)
   - "Select identity from label matrix" → "Tap any text to use it"
   - Removed cryptic "Cycle" terminology, added countdown seconds

2. Feature Discoverability
   - Added helpful descriptions to Admin manager sections
   - Scanner status message now hints at zoom and tap features
   - Concrete examples in input placeholders

3. Help & Documentation
   - User Management: "Create accounts and control access"
   - Category Groups: "Organize items by type or location"
   - Sign Out: clearer procedure description

Build: passes with zero errors
---
 frontend/app/page.tsx                |  4 ++--
 frontend/components/AdminOverlay.tsx | 16 +++++++++++-----
 frontend/components/Scanner.tsx      | 14 +++++++-------
 3 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/frontend/app/page.tsx b/frontend/app/page.tsx
index cd602226..24fdc9a6 100644
--- a/frontend/app/page.tsx
+++ b/frontend/app/page.tsx
@@ -705,12 +705,12 @@ export default function Home() {
                        />
                     </div>
                     <div className="bg-slate-900/80 py-2.5 px-4 rounded-[1.2rem] border border-slate-800 focus-within:border-primary/50 transition-colors group">
-               <label className="text-xs text-slate-400 font-bold mb-0.5 block group-focus-within:text-primary transition-colors tracking-tight">OCR Matching Key</label>
+               <label className="text-xs text-slate-400 font-bold mb-0.5 block group-focus-within:text-primary transition-colors tracking-tight">Item ID or Code</label>
                        <textarea
                          value={editedItem.ocr_text || ''}
                          onChange={e => setEditedItem({ ...editedItem, ocr_text: e.target.value })}
                          className="w-full bg-slate-950 border border-slate-800 rounded-xl py-3 px-4 text-sm font-bold outline-none text-slate-400 resize-none h-12"
-                         placeholder="Paste identification string here..."
+                         placeholder="e.g., SKU-12345 or barcode text..."
                        />
                     </div>
                   </div>
diff --git a/frontend/components/AdminOverlay.tsx b/frontend/components/AdminOverlay.tsx
index 8fb3b4da..d48ea353 100644
--- a/frontend/components/AdminOverlay.tsx
+++ b/frontend/components/AdminOverlay.tsx
@@ -134,7 +134,10 @@ export default function AdminOverlay({
         <div className="flex-1 overflow-y-auto p-6 space-y-8">
           <section className="space-y-4">
             <div className="flex items-center justify-between">
-              <h3 className="text-sm font-black text-slate-400">User Management</h3>
+              <div>
+                <h3 className="text-sm font-black text-slate-400">User Management</h3>
+                <p className="text-xs text-slate-500 mt-0.5">Create accounts and control access</p>
+              </div>
               <button
                 onClick={() => setShowCreateUserModal(true)}
                 className="flex items-center gap-1 text-xs font-black text-primary hover:text-blue-400 focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none rounded px-1"
@@ -180,7 +183,10 @@ export default function AdminOverlay({
 
           <section className="space-y-4">
             <div className="flex items-center justify-between">
-              <h3 className="text-sm font-black text-slate-400">Category Groups</h3>
+              <div>
+                <h3 className="text-sm font-black text-slate-400">Category Groups</h3>
+                <p className="text-xs text-slate-500 mt-0.5">Organize items by type or location</p>
+              </div>
               <button
                 onClick={() => setShowCreateCategoryModal(true)}
                 className="flex items-center gap-1 text-xs font-black text-primary hover:text-blue-400 focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none rounded px-1"
@@ -226,9 +232,9 @@ export default function AdminOverlay({
           <section className="p-6 bg-slate-800/30 rounded-3xl border border-slate-800 space-y-4">
             <div className="flex items-center gap-2 text-rose-500">
               <AlertTriangle size={16} />
-              <p className="text-sm font-black">Logout</p>
+              <p className="text-sm font-black">Sign Out</p>
             </div>
-            <p className="text-xs text-slate-500">Exit current session and return to identity check.</p>
+            <p className="text-xs text-slate-500">End your session and return to the login screen.</p>
             <button
               onClick={() => {
                 import('@/lib/auth').then(m => m.clearAuth());
@@ -236,7 +242,7 @@ export default function AdminOverlay({
               }}
               className="w-full bg-rose-500/10 hover:bg-rose-500/20 text-rose-500 border border-rose-500/20 font-black py-3 rounded-xl transition-all flex items-center justify-center gap-2 focus-visible:ring-2 focus-visible:ring-rose-500 focus-visible:outline-none"
             >
-              <LogOut size={16} /> End Session
+              <LogOut size={16} /> Sign Out
             </button>
           </section>
         </div>
diff --git a/frontend/components/Scanner.tsx b/frontend/components/Scanner.tsx
index 2326f601..69d17b97 100644
--- a/frontend/components/Scanner.tsx
+++ b/frontend/components/Scanner.tsx
@@ -257,14 +257,14 @@ export default function Scanner({ onScanSuccess, onOCRMatch, paused }: ScannerPr
             </div>
             <div className="p-6 bg-slate-900/90 border-t border-slate-800 flex flex-col gap-4">
                <div className="flex flex-col items-center gap-1">
-                 <p className="text-sm font-black text-white italic text-center">Protocol Detected</p>
-                 <p className="text-xs text-slate-500 font-black text-center">Select identity from label matrix</p>
+                 <p className="text-sm font-black text-white italic text-center">Text Found</p>
+                 <p className="text-xs text-slate-500 font-black text-center">Tap any text to use it</p>
                </div>
-               <button 
+               <button
                  onClick={() => { setIsSelecting(false); setCapturedImage(null); setCountdown(4); }}
                  className="w-full py-4 bg-slate-800 hover:bg-slate-700 text-white rounded-2xl font-black text-xs transition-all active:scale-95 border border-slate-700"
                >
-                 Abort Cycle
+                 Cancel
                </button>
             </div>
           </div>
@@ -330,9 +330,9 @@ export default function Scanner({ onScanSuccess, onOCRMatch, paused }: ScannerPr
                   <>
                     <Search className={cn("text-slate-600 transition-colors group-hover:text-primary", !isStarted && "opacity-20")} size={18} />
                     <div className="flex flex-col">
-                        <span className="text-xs text-slate-500 font-black leading-none">Optical Assist</span>
+                        <span className="text-xs text-slate-500 font-black leading-none">Smart Scan</span>
                         <span className="text-xs font-black text-primary leading-tight tabular-nums">
-                            {countdown === 0 ? "Scanning" : `${countdown}s Cycle`}
+                            {countdown === 0 ? "Scanning" : `${countdown}s`}
                         </span>
                     </div>
                   </>
@@ -349,7 +349,7 @@ export default function Scanner({ onScanSuccess, onOCRMatch, paused }: ScannerPr
         <div className="w-full flex justify-center items-center gap-2">
           <div className="w-1 h-1 rounded-full bg-green-500 animate-pulse" />
           <p className="text-xs text-slate-600 font-black">
-            Optical Data Stream Active
+            Scanner active · Use zoom or tap scan
           </p>
         </div>
       </div>