[EPIC][MOBILE]: Mobile-first responsive redesign

[crivetimihai]

📱 Epic: Mobile-First Responsive Redesign

Goal

Optimize the Admin UI for tablets and mobile devices with a responsive layout, touch-friendly controls, and optional PWA installation for quick access from mobile devices.

Why Now?

1. On-the-Go Management: Admins need to check status and respond to issues from mobile
2. Tablet Usage: Many users browse admin UIs on tablets
3. Modern Expectation: Responsive design is baseline for web apps
4. PWA Benefits: Installable app, offline support, push notifications

---

📖 User Stories

US-1: Responsive Layout

As a mobile user
I want the UI to adapt to my screen size
So that I can use it without horizontal scrolling

Acceptance Criteria:

• Single-column layout on mobile (<768px)
• Collapsible sidebar navigation
• Responsive tables (card view on mobile)
• Touch-friendly button sizes (44px minimum)
• No horizontal overflow

US-2: Mobile Navigation

As a mobile user
I want easy navigation on small screens
So that I can access all sections quickly

Acceptance Criteria:

• Hamburger menu for navigation
• Bottom navigation bar for key sections
• Swipe gestures for tab switching
• Back button support
• Breadcrumbs for deep navigation

US-3: Touch-Friendly Controls

As a touch screen user
I want controls sized for touch input
So that I can tap accurately

Acceptance Criteria:

• Minimum 44x44px touch targets
• Adequate spacing between interactive elements
• No hover-only interactions
• Long-press for context menus
• Swipe to delete in lists

US-4: PWA Installation

As a mobile user
I want to install the Admin UI as an app
So that I can access it quickly from my home screen

Acceptance Criteria:

• Web App Manifest configured
• "Add to Home Screen" prompt
• App icon and splash screen
• Standalone display mode
• Works offline (cached shell)

US-5: Responsive Tables

As a mobile user
I want tables to be readable on small screens
So that I can view entity data without scrolling sideways

Acceptance Criteria:

• Card view for tables on mobile
• Priority columns shown, others collapsed
• Expand to see all fields
• Maintain sort/filter functionality
• Pagination optimized for touch

---

📋 Implementation Tasks

Phase 1: Responsive Foundation

• Audit current breakpoints and media queries
• Implement mobile-first CSS approach
• Add responsive utility classes
• Test on various device sizes

Phase 2: Navigation

• Create collapsible sidebar component
• Add hamburger menu toggle
• Implement bottom navigation bar
• Add swipe gesture support
• Ensure keyboard accessibility maintained

Phase 3: Tables & Components

• Create responsive table component
• Implement card view variant
• Add column priority system
• Make modals full-screen on mobile
• Optimize forms for touch

Phase 4: Touch Optimization

• Audit touch target sizes
• Add touch-specific interactions
• Implement pull-to-refresh
• Add swipe actions in lists
• Test on actual devices

Phase 5: PWA Setup

• Create Web App Manifest
• Add service worker for caching
• Design app icons (multiple sizes)
• Create splash screens
• Implement offline fallback page

---

⚙️ Breakpoints

/* Mobile-first breakpoints */
:root {
  --breakpoint-sm: 640px;   /* Large phones */
  --breakpoint-md: 768px;   /* Tablets */
  --breakpoint-lg: 1024px;  /* Laptops */
  --breakpoint-xl: 1280px;  /* Desktops */
}

/* Example usage */
.sidebar {
  display: none; /* Hidden on mobile */
}

@media (min-width: 768px) {
  .sidebar {
    display: block;
    width: 250px;
  }
}

PWA Manifest

{
  "name": "MCP Gateway Admin",
  "short_name": "MCP Admin",
  "start_url": "/admin",
  "display": "standalone",
  "background_color": "#1f2937",
  "theme_color": "#3b82f6",
  "icons": [
    { "src": "/static/icons/icon-192.png", "sizes": "192x192" },
    { "src": "/static/icons/icon-512.png", "sizes": "512x512" }
  ]
}

---

✅ Success Criteria

• UI usable on 320px width screens
• No horizontal scrolling on mobile
• Touch targets ≥44px
• Navigation works on mobile
• Tables readable on mobile
• PWA installable
• Lighthouse mobile score >90

---

📚 References

• Responsive Design Patterns
• Touch Target Guidelines
• PWA Documentation
• Service Worker Cookbook