From 10d75619bfa57de5b4b18b8e38252fdbc2728dc2 Mon Sep 17 00:00:00 2001
From: Daniel Bedeleanu <daniel.bedeleanu@emag.ro>
Date: Wed, 15 Apr 2026 11:39:50 +0300
Subject: [PATCH] docs: update documentation with mobile stat cards UI
 improvements

- Added StatCard component description to README
- Updated frontend architecture in PROJECT_ARCHITECTURE.md
- Documented responsive design improvements (v1.9.21+)
- Mobile-first responsive design for inventory management
---
 PROJECT_ARCHITECTURE.md |  8 +++++++-
 README.md               | 13 ++++++++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/PROJECT_ARCHITECTURE.md b/PROJECT_ARCHITECTURE.md
index 36a124fa..ae6d5bde 100644
--- a/PROJECT_ARCHITECTURE.md
+++ b/PROJECT_ARCHITECTURE.md
@@ -16,8 +16,14 @@ A unified system to maintain an inventory of "items" and their quantities, inclu
 
 ### 2.2 Frontend (Web & PWA)
 - **Architecture:** Next.js 15+ (App Router)
-- **Styling:** Tailwind CSS (Readability-first config)
+- **Styling:** Tailwind CSS (Readability-first config, mobile-first responsive)
 - **Icons:** Lucide Icons (React components)
+- **Components:** 
+  - **StatCard** (v1.9.21+): Responsive stat display component for mobile/desktop
+    - Two-column flexbox layout (label left, number right)
+    - Responsive font sizing with Tailwind breakpoints (text-sm→md, text-lg→xl)
+    - Label truncation with ellipsis for overflow handling
+    - Accessibility: `role="status"`, `aria-hidden` on decorative icons
 - **Offline persistence:** Dexie.js (IndexedDB wrapper)
 - **Scanner:** `html5-qrcode` (Client-side, offline-only)
 - **Sync:** Axios with bulk-sync idempotency (UUID-based)
diff --git a/README.md b/README.md
index c270ad09..37e846f6 100644
--- a/README.md
+++ b/README.md
@@ -39,9 +39,20 @@ To generate a clean production package and snapshot the current state:
 
 ---
 
+## 🎨 Recent UI/UX Improvements (v1.9.21+)
+
+### Mobile-First Responsive Design
+- **StatCard Component:** Reusable, responsive stat display component for mobile phones
+  - Two-column flexbox layout (label left, number right) prevents text overflow on narrow screens
+  - Responsive font sizing: `text-sm md:text-base` (labels), `text-lg md:text-xl` (numbers)
+  - Automatic label truncation with ellipsis for long text
+  - Accessible markup with `role="status"` and `aria-hidden` attributes
+- **Pages Updated:** Inventory (Categories, Item Types, Total Boxes), Logs (Total Events, Check in/out), Admin (Local Archives)
+- **Tested on:** iPhone SE (375px), iPhone 12 (390px), iPhone 14 Pro Max (430px), tablets (768px), desktop (1024px)
+
 ## 🏗 Technical Overview
 *   **Backend:** FastAPI (Python 3.12+)
-*   **Frontend:** Next.js 15+ (React PWA)
+*   **Frontend:** Next.js 15+ (React PWA) with responsive Tailwind CSS
 *   **Database:** SQLite (SQLAlchemy) with Dexie.js (IndexedDB) for client-side sync.
 *   **Proxy:** Caddy (Docker) or local-ssl-proxy (Standalone/Dev).
 *   **AI Engine:** Google Gemini (Generative AI SDK).