tfm_ainventory/docs/superpowers/plans/2026-04-15-mobile-stat-cards-implementation.md

Mobile Stat Cards Responsive Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Implement two-column flexbox layout for stat cards across Inventory, Logs, and Admin pages to fix content overflow on mobile iPhone screens.

Architecture: Create a reusable StatCard component with responsive Tailwind classes (flex justify-between, responsive font sizing, label truncation). Replace inline stat displays on three pages with this component.

Tech Stack: React, Next.js 15, Tailwind CSS, Lucide Icons

---

File Structure

Files to Create:

• frontend/components/StatCard.tsx — Reusable stat card component

Files to Modify:

• frontend/app/inventory/page.tsx — Replace stat displays with StatCard component
• frontend/app/logs/page.tsx — Replace stat displays with StatCard component
• frontend/app/admin/page.tsx — Replace stat displays with StatCard component

---

Task 1: Create Reusable StatCard Component

Files:

• Create: frontend/components/StatCard.tsx

• Step 1: Create the StatCard component file

Create frontend/components/StatCard.tsx:

import React from 'react';
import { LucideIcon } from 'lucide-react';

interface StatCardProps {
  label: string;
  value: number;
  icon?: LucideIcon;
}

export default function StatCard({ label, value, icon: Icon }: StatCardProps) {
  return (
    <div className="flex justify-between items-center gap-2 p-4 bg-slate-900 rounded-lg">
      {/* Icon + Label Container */}
      <div className="flex items-center gap-2 min-w-0">
        {Icon && <Icon className="w-5 h-5 text-primary flex-shrink-0" />}
        <span className="text-sm md:text-base text-slate-400 truncate">
          {label}
        </span>
      </div>

      {/* Number (Right) */}
      <span className="text-lg md:text-xl font-black text-white whitespace-nowrap">
        {value}
      </span>
    </div>
  );
}

Key Implementation Details:

• flex justify-between items-center — Label left, number right, vertically centered

• gap-2 — 8px spacing between label and number

• p-4 — 16px padding on mobile

• bg-slate-900 rounded-lg — Dark background, rounded corners

• min-w-0 — Allows label container to shrink (enables truncate)

• text-sm md:text-base — Label: 14px mobile, 16px desktop+

• truncate — Label ellipsis if too long

• text-lg md:text-xl — Number: 18px mobile, 20px desktop+

• whitespace-nowrap — Number never wraps

• flex-shrink-0 on icon — Icon doesn't shrink

• Step 2: Commit the component

git add frontend/components/StatCard.tsx
git commit -m "feat: create reusable StatCard component with responsive layout

- Two-column flexbox layout (label left, number right)
- Responsive font sizing (sm/md breakpoints)
- Label truncation for overflow handling
- Optional icon support via Lucide
- Ready for use across Inventory, Logs, Admin pages"

---

Task 2: Update Inventory Page Stat Cards

Files:

• Modify: frontend/app/inventory/page.tsx

• Step 1: Read the current inventory page to find stat card implementations

Look for sections displaying:

• "Categories" with count
• "Item Types" with count
• "Total Boxes" with count

Expected current pattern (inline flex layout):

<div className="flex items-center gap-2">
  <Layers className="text-primary" />
  <div>
    <p className="text-xs text-slate-500">Categories</p>
    <p className="text-lg font-black">{categoriesCount}</p>
  </div>
</div>

• Step 2: Import StatCard component at top of file

Add to imports:

import StatCard from '@/components/StatCard';

(Adjust import path based on actual file location)

• Step 3: Replace Categories stat display with StatCard

Find the Categories display section and replace with:

<StatCard 
  label="Categories" 
  value={categoriesCount} 
  icon={Layers}
/>

Ensure Layers icon is imported from lucide-react (should already be if used previously).

• Step 4: Replace Item Types stat display with StatCard

Find the Item Types display section and replace with:

<StatCard 
  label="Item Types" 
  value={itemTypesCount} 
  icon={Package}
/>

Ensure Package icon is imported from lucide-react (standard Lucide icon for item types).

• Step 5: Replace Total Boxes stat display with StatCard

Find the Total Boxes display section and replace with:

<StatCard 
  label="Total Boxes" 
  value={totalBoxesCount} 
  icon={Box}
/>

Ensure Box icon is imported from lucide-react.

• Step 6: Verify all three stat cards are now using StatCard component

Check that the Inventory page displays three stat cards in a consistent layout.

• Step 7: Commit the changes

git add frontend/app/inventory/page.tsx
git commit -m "fix: refactor Inventory page stat cards to use StatCard component

- Replace Categories, Item Types, Total Boxes with StatCard
- Fixes mobile content overflow with two-column flexbox layout
- Responsive font sizing for mobile/desktop
- Label truncation for long text"

---

Task 3: Update Logs Page Stat Cards

Files:

• Modify: frontend/app/logs/page.tsx

• Step 1: Read the current logs page to find stat card implementations

Look for "Total Events" or similar stat display with a count.

• Step 2: Import StatCard component

Add to imports:

import StatCard from '@/components/StatCard';

• Step 3: Replace Total Events stat display with StatCard

Find the Total Events display section and replace with:

<StatCard 
  label="Total Events" 
  value={totalEventsCount} 
  icon={LogSquare}
/>

Ensure LogSquare icon is imported from lucide-react (or use FileText, ListChecks, or other appropriate icon if LogSquare doesn't exist).

• Step 4: Verify the stat card displays correctly

Check that the Logs page displays the Total Events stat in the new layout.

• Step 5: Commit the changes

git add frontend/app/logs/page.tsx
git commit -m "fix: refactor Logs page stat cards to use StatCard component

- Replace Total Events display with StatCard
- Fixes mobile content overflow with responsive layout
- Consistent styling with Inventory page"

---

Task 4: Update Admin Page Stat Cards

Files:

• Modify: frontend/app/admin/page.tsx

• Step 1: Read the current admin page to find stat card implementations

Look for any label + number stat displays (e.g., "Users", "Sessions", "Audit Logs", etc.).

• Step 2: Import StatCard component

Add to imports:

import StatCard from '@/components/StatCard';

• Step 3: Replace all stat displays with StatCard

For each stat display on the Admin page, replace with:

<StatCard 
  label="[Stat Label]" 
  value={[Count Variable]} 
  icon={[AppropriateIcon]}
/>

Example (if there's a "Users" stat):

<StatCard 
  label="Users" 
  value={usersCount} 
  icon={Users}
/>

Map appropriate Lucide icons to each stat:

• Users → Users

• Sessions → Zap or Activity

• Audit Logs → LogSquare or FileText

• Admins → Shield

• Active Sessions → Activity

• Step 4: Verify all admin stat cards are updated

Check that the Admin page displays all stats with consistent StatCard styling.

• Step 5: Commit the changes

git add frontend/app/admin/page.tsx
git commit -m "fix: refactor Admin page stat cards to use StatCard component

- Replace all stat displays with StatCard
- Fixes mobile content overflow with responsive layout
- Consistent styling across all admin stats"

---

Task 5: Test on Mobile Viewport

Files:

• Test: All three pages (Inventory, Logs, Admin)

• Step 1: Start the development server

./start_server.sh

Expected: Frontend runs on http://localhost:8907

• Step 2: Open browser DevTools and set mobile viewport

1. Open DevTools (F12 or Cmd+Shift+I)
2. Toggle Device Toolbar (Cmd+Shift+M or Ctrl+Shift+M)
3. Set to iPhone SE (375px) or iPhone 12 (390px)

• Step 3: Test Inventory page on mobile

Navigate to Inventory page. Verify:

• ✓ "Categories 2" — Label on left, number on right, no overflow

• ✓ "Item Types 6" — Label on left, number on right, no overflow

• ✓ "Total Boxes 2" — Label on left, number on right, no overflow

• ✓ All text is visible (not cut off)

• ✓ Cards are properly padded

• Step 4: Test Logs page on mobile

Navigate to Logs page. Verify:

• ✓ "Total Events [number]" — Label and number both visible, no overflow

• ✓ Text formatting is correct

• Step 5: Test Admin page on mobile

Navigate to Admin page. Verify:

• ✓ All stat cards display correctly without overflow

• ✓ Labels and numbers are properly aligned

• Step 6: Test on different mobile widths

Resize browser to test at:

• 320px (iPhone SE smallest)
• 375px (iPhone SE)
• 390px (iPhone 12)
• 430px (iPhone 14 Pro Max)

Verify no overflow occurs and layout remains stable.

• Step 7: Test on tablet and desktop

Resize to:

• 768px (tablet) — verify md: breakpoint applies

• 1024px (desktop) — verify lg: breakpoint applies

• Step 8: Test with long labels

(If possible, temporarily update a label to test truncation) Example: <StatCard label="Total Events in System Very Long Name" value={42} />

Verify: Label shows ellipsis ("Total Events in System...") and doesn't overflow.

• Step 9: No test failures

Run any existing tests to ensure no regressions:

npm run test

Expected: All tests pass (or maintain same pass rate as before)

• Step 10: Commit test verification notes (optional)

git add .
git commit -m "test: verify stat card responsive layout on mobile viewports

- iPhone SE (375px): No overflow ✓
- iPhone 12 (390px): No overflow ✓
- iPhone 14 Pro Max (430px): No overflow ✓
- Tablet (768px): Desktop styling ✓
- Desktop (1024px): Large text ✓
- Long label truncation: Ellipsis works ✓"

---

Task 6: Final Verification & Documentation Update

Files:

• Review: All modified pages

• Update: dev_docs/SESSION_STATE.md (handover)

• Step 1: Verify all commits are in place

git log --oneline -6

Expected output includes:

• feat: create reusable StatCard component...

• fix: refactor Inventory page stat cards...

• fix: refactor Logs page stat cards...

• fix: refactor Admin page stat cards...

• (optional) test: verify stat card responsive layout...

• Step 2: Check for any remaining inline stat displays

Search the codebase for any remaining old-style stat displays:

grep -r "text-xs text-slate-500" frontend/app --include="*.tsx" | grep -i "categor\|item\|box\|event\|user\|session"

If found, replace with StatCard component.

• Step 3: Update SESSION_STATE.md handover

Add to dev_docs/SESSION_STATE.md:

### Mobile Stat Cards Responsive Fix (Completed)

**Issue:** Stat card content overflowed outside card boundaries on iPhone mobile screens (< 640px).

**Solution:** Created reusable `StatCard` component with two-column flexbox layout:
- Label (left, flexible, truncates if long)
- Number (right, fixed, never wraps)
- Responsive font sizes: `text-sm md:text-base` (label), `text-lg md:text-xl` (number)

**Pages Fixed:**
- ✓ Inventory page (Categories, Item Types, Total Boxes)
- ✓ Logs page (Total Events)
- ✓ Admin page (all stat displays)

**Verification:**
- ✓ iPhone SE (375px): No overflow
- ✓ iPhone 12 (390px): No overflow
- ✓ Tablet/Desktop: Responsive scaling works
- ✓ Long labels: Truncate with ellipsis
- ✓ All tests pass

**Files Changed:**
- Created: `frontend/components/StatCard.tsx`
- Modified: `frontend/app/inventory/page.tsx`
- Modified: `frontend/app/logs/page.tsx`
- Modified: `frontend/app/admin/page.tsx`

**Next Steps:** Deploy to remote server and verify on real iPhone device if possible.

• Step 4: Commit the handover update

git add dev_docs/SESSION_STATE.md
git commit -m "docs: update session state - mobile stat cards responsive fix complete

- StatCard component created and integrated
- All three pages (Inventory, Logs, Admin) updated
- Mobile testing verified (375px-430px widths)
- Responsive breakpoints working correctly"

• Step 5: Verify no uncommitted changes

git status

Expected: working tree clean

• Step 6: Review the spec coverage one final time

Check docs/superpowers/specs/2026-04-15-mobile-stat-cards-responsive-design.md:

Spec Requirements vs. Implementation:

• ✓ Two-column flexbox layout implemented
• ✓ Label left, number right implemented
• ✓ Responsive font sizing (sm/md/lg) implemented
• ✓ Label truncation for long text implemented
• ✓ Inventory page stat cards fixed
• ✓ Logs page stat cards fixed
• ✓ Admin page stat cards fixed
• ✓ Mobile testing completed
• ✓ No regressions on desktop/tablet

All spec requirements are covered.

---

Summary

6 Tasks, ~45-60 minutes total:

1. Create StatCard component (5 min)
2. Update Inventory page (10 min)
3. Update Logs page (10 min)
4. Update Admin page (10 min)
5. Test on mobile (15 min)
6. Final verification & docs (5 min)

Commits Created: 5-6 commits with clear, descriptive messages

Testing: Manual mobile viewport testing across iPhone SE, 12, 14 Pro Max widths

Outcome: All stat cards on Inventory, Logs, and Admin pages now display with responsive two-column layout. No content overflow on mobile. Consistent styling across all pages.

---