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`:

```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**

```bash
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):
```tsx
<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:
```tsx
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:

```tsx
<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:

```tsx
<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:

```tsx
<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**

```bash
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:
```tsx
import StatCard from '@/components/StatCard';
```

- [ ] **Step 3: Replace Total Events stat display with StatCard**

Find the Total Events display section and replace with:

```tsx
<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**

```bash
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:
```tsx
import StatCard from '@/components/StatCard';
```

- [ ] **Step 3: Replace all stat displays with StatCard**

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

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

Example (if there's a "Users" stat):
```tsx
<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**

```bash
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**

```bash
./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:

```bash
npm run test
```

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

- [ ] **Step 10: Commit test verification notes (optional)**

```bash
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**

```bash
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:

```bash
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`:

```markdown
### 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**

```bash
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**

```bash
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.

---