docs: add comprehensive P5 Mobile User Experience section to ROADMAP.md

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -4,7 +4,7 @@
 > **Current Version:** v0.5.x
 > **Spec Version:** @objectstack/spec v3.0.0
 > **Client Version:** @objectstack/client v3.0.0
-> **Current Priority:** 🎯 Developer Experience · User Experience · Component Excellence · Documentation
+> **Current Priority:** 🎯 Developer Experience · User Experience · Component Excellence · Documentation · Mobile UX
 
 ---
 
@@ -20,6 +20,7 @@ ObjectUI is a universal Server-Driven UI (SDUI) engine built on React + Tailwind
 2. **🎨 User Experience (UX)** — Console polish, i18n completeness, accessibility, performance at scale
 3. **🧩 Component Excellence** — Every component polished, well-tested, and delightful to use
 4. **📖 Documentation** — Complete API docs, rich Storybook stories, tutorials, and guides
+5. **📱 Mobile User Experience** — Responsive layouts, touch-friendly interactions, PWA support
 
 > 📄 Companion documents:
 > - [SPEC_COMPLIANCE_EVALUATION.md](./SPEC_COMPLIANCE_EVALUATION.md) — Per-package spec compliance (98% current)
@@ -283,6 +284,193 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 
 ---
 
+### P5. Mobile User Experience 📱
+
+**Goal:** Every component and page delivers a native-quality experience on phones and tablets — responsive layout, touch-friendly interactions, and fast performance on mobile networks.
+
+> **Existing Infrastructure:** `@object-ui/mobile` provides `useBreakpoint` (isMobile/isTablet/isDesktop), `useResponsive`, `useGesture`, `useTouchTarget`, `MobileProvider`, and `ResponsiveContainer`. `@object-ui/layout` provides `ResponsiveGrid` with Tailwind-aligned breakpoints. These building blocks are production-ready but under-adopted across plugin views and the Console app.
+
+#### P5.1 Plugin Views — Mobile-First Layouts
+
+Each plugin view must work seamlessly from 320px (small phone) to 2560px (ultrawide).
+
+##### ObjectGrid (`plugin-grid`)
+- [ ] Wrap data table in `overflow-x-auto` container for horizontal scroll on mobile
+- [ ] Add responsive toolbar: stack filter/sort/search controls vertically below `sm:` breakpoint
+- [ ] Collapse non-essential columns on mobile via `hidden sm:table-cell` pattern
+- [ ] Scale row padding: `px-2 py-1.5 sm:px-3 sm:py-2 md:px-4 md:py-2.5`
+- [ ] Add mobile card-view fallback for screens below 480px (toggle between table and card layout)
+- [ ] Ensure touch targets ≥ 44px for all interactive row elements
+
+##### ObjectKanban (`plugin-kanban`)
+- [ ] Stack columns vertically on mobile with horizontal swipe navigation between columns
+- [ ] Scale card sizing: `p-2 sm:p-3 md:p-4` with responsive typography
+- [ ] Add touch-friendly drag-and-drop via `useGesture` (long-press to initiate, haptic feedback)
+- [ ] Column headers: `text-sm sm:text-base` with truncation on mobile
+- [ ] Add column count badge and swipe indicator on mobile
+- [ ] Limit visible card fields on mobile (show title + status only, expand on tap)
+
+##### ObjectForm (`plugin-form`)
+- [ ] Ensure mobile-first column stacking: 1 column on `xs`, 2 on `sm:`, 3+ on `md:`
+- [ ] Scale field labels: `text-xs sm:text-sm` with proper spacing
+- [ ] Make action buttons full-width on mobile: `w-full sm:w-auto`
+- [ ] Increase touch targets for all form controls (min 44×44px)
+- [ ] Optimize select/dropdown fields for mobile (bottom sheet pattern on phones)
+- [ ] Ensure date pickers and multi-select fields are mobile-friendly
+
+##### ObjectDashboard (`plugin-dashboard`)
+- [ ] Implement responsive grid: `grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4`
+- [ ] Scale widget padding: `p-3 sm:p-4 md:p-6` per widget card
+- [ ] Stack dashboard header controls on mobile (title above actions)
+- [ ] Add swipeable widget carousel option for mobile
+- [ ] Chart widgets: reduce axis label density on mobile
+
+##### ObjectCalendar (`plugin-calendar`)
+- [ ] Replace fixed `h-[calc(100vh-200px)]` with responsive height: `h-[calc(100vh-120px)] sm:h-[calc(100vh-160px)] md:h-[calc(100vh-200px)]`
+- [ ] Default to day or agenda view on mobile (month view unreadable on phones)
+- [ ] Add swipe-to-navigate between days/weeks on mobile via `useGesture`
+- [ ] Scale event text: `text-xs sm:text-sm` with single-line truncation
+- [ ] Make event creation touch-friendly (long-press on timeslot)
+
+##### ObjectTimeline (`plugin-timeline`)
+- [ ] Switch from side-by-side to single-column layout on mobile
+- [ ] Scale item padding: `p-2 sm:p-3 md:p-4` with responsive typography
+- [ ] Truncate event descriptions on mobile with "Show more" expand
+- [ ] Add pull-to-refresh via `usePullToRefresh` for timeline data
+
+##### ObjectList (`plugin-list`)
+- [ ] Stack toolbar controls vertically on mobile with collapsible filter panel
+- [ ] Scale search bar: `w-full sm:w-48 lg:w-64` (full-width on mobile)
+- [ ] Responsive list item padding: `px-2 sm:px-3 md:px-4`
+- [ ] Ensure action menus use bottom sheet on mobile instead of popovers
+- [ ] Touch-friendly row selection (checkbox size ≥ 44px)
+
+##### DetailView (`plugin-detail`)
+- [ ] Stack header actions vertically on narrow screens: `flex-col sm:flex-row`
+- [ ] Full-width action buttons on mobile: `w-full sm:w-auto`
+- [ ] Scale section padding: `p-3 sm:p-4 md:p-6`
+- [ ] Convert metadata panel to bottom drawer on mobile
+- [ ] Increase field value touch targets for copy-to-clipboard
+
+##### Charts (`plugin-charts`)
+- [ ] Set responsive chart heights: `h-48 sm:h-64 md:h-80 lg:h-96`
+- [ ] Reduce axis label count on mobile to prevent overlap
+- [ ] Enable touch-to-inspect data points (tooltip on tap)
+- [ ] Stack legend below chart on mobile: `flex-col sm:flex-row`
+
+##### Map (`plugin-map`)
+- [ ] Enable pinch-to-zoom and two-finger pan on mobile
+- [ ] Scale info popup sizing for mobile screens
+- [ ] Add mobile-friendly location search with bottom sheet
+- [ ] Ensure map controls (zoom, layer toggle) are touch-accessible
+
+##### Gantt (`plugin-gantt`)
+- [ ] Add horizontal scroll container with touch momentum
+- [ ] Scale bar heights: `h-6 sm:h-8 md:h-10`
+- [ ] Collapse task details on mobile (show name only, expand on tap)
+- [ ] Add responsive zoom levels (day view on mobile, week on tablet, month on desktop)
+
+#### P5.2 Console Pages — Responsive Layouts
+
+##### AppHeader
+- [ ] Ensure all header actions are accessible on mobile (overflow menu for hidden actions)
+- [ ] Add mobile-specific command palette trigger (prominent search icon)
+- [ ] Scale header height: `h-12 sm:h-14 md:h-16`
+- [ ] Responsive breadcrumb: show only current page on mobile, full path on desktop
+
+##### AppSidebar
+- [ ] Auto-collapse to icon-only mode on tablet, full overlay on mobile
+- [ ] Add swipe-from-edge gesture to open sidebar on mobile via `useGesture`
+- [ ] Scale menu item padding for touch: `py-2.5 sm:py-2` (larger on mobile)
+- [ ] Bottom navigation bar option for mobile (5-item tab bar)
+
+##### DashboardView (Console)
+- [ ] Stack title and metadata toggle vertically on mobile
+- [ ] Scale heading: `text-lg sm:text-xl md:text-2xl`
+- [ ] Add responsive padding: `p-3 sm:p-4 md:p-6 lg:p-8`
+- [ ] Optimize metadata panel as collapsible accordion on mobile
+
+##### RecordDetailView
+- [ ] Scale dialog width: `w-[calc(100vw-1rem)] sm:w-[calc(100vw-2rem)] md:max-w-2xl lg:max-w-4xl`
+- [ ] Stack field label and value vertically on mobile
+- [ ] Add responsive padding: `p-3 sm:p-4 md:p-6`
+- [ ] Ensure inline editing works with on-screen keyboard
+
+##### Create/Edit Dialogs
+- [ ] Full-screen modal on mobile: `h-[100dvh] sm:h-auto sm:max-h-[90vh]`
+- [ ] Sticky action buttons at bottom on mobile
+- [ ] Add swipe-to-dismiss for mobile dialogs
+
+#### P5.3 Core Component Primitives
+
+##### DataTable (`components/renderers/complex`)
+- [ ] Add outer `overflow-x-auto` wrapper with `-webkit-overflow-scrolling: touch`
+- [ ] Scale pagination controls: full-width on mobile with larger touch targets
+- [ ] Responsive column visibility system (priority-based column hiding)
+- [ ] Mobile-optimized search/filter bar: full-width, collapsible
+- [ ] Horizontal scroll indicator (shadow/gradient) on mobile
+
+##### Form Renderer (`components/renderers/form`)
+- [ ] Verify responsive column mapping works correctly for all column counts (1–4)
+- [ ] Ensure wizard/stepper variant shows 1 step at a time on mobile
+- [ ] Scale step indicators for mobile: `text-xs sm:text-sm`, smaller circles
+- [ ] Full-width submit/cancel buttons on mobile
+
+##### Navigation Components
+- [ ] Breadcrumb: truncate to current + parent on mobile with "..." overflow
+- [ ] Tab navigation: horizontal scroll with `overflow-x-auto` for many tabs
+- [ ] DropdownMenu: use bottom sheet pattern on mobile via `useIsMobile()` detection
+
+#### P5.4 Mobile Infrastructure Enhancements
+
+##### Touch & Gesture System
+- [ ] Integrate `usePullToRefresh` into all data-fetching views (Grid, List, Timeline, Calendar)
+- [ ] Add swipe-to-go-back gesture for Console navigation
+- [ ] Integrate `useTouchTarget` hook to enforce minimum 44px touch targets across all interactive elements
+- [ ] Add haptic feedback triggers for drag-and-drop completion
+
+##### Performance on Mobile Networks
+- [ ] Implement progressive image loading for all image fields and avatars
+- [ ] Add connection-aware data fetching (reduce page size on slow connections)
+- [ ] Enable service worker caching for static assets via `registerServiceWorker`
+- [ ] Add `loading="lazy"` to all below-fold images and iframes
+
+##### PWA Support
+- [ ] Integrate `MobileProvider` into Console app root with PWA configuration
+- [ ] Generate app manifest via `generatePWAManifest()` utility
+- [ ] Add app install prompt for mobile browsers
+- [ ] Implement offline indicator and cached-data fallback
+
+##### Viewport & Input Handling
+- [ ] Handle virtual keyboard resize (100dvh instead of 100vh for mobile)
+- [ ] Prevent zoom on input focus (`font-size: 16px` minimum for inputs)
+- [ ] Add viewport meta tag validation in Console HTML template
+- [ ] Support safe-area-inset for notched devices (`env(safe-area-inset-*)`)
+
+#### P5.5 Testing & Quality Assurance
+
+- [ ] Add Playwright mobile viewport tests (iPhone SE 375px, iPhone 14 390px, iPad 768px)
+- [ ] Add visual regression tests for all views at mobile breakpoints
+- [ ] Add touch interaction tests (swipe, pinch, long-press) via Playwright touch emulation
+- [ ] Verify all views pass axe-core at mobile viewport sizes
+- [ ] Add Storybook mobile viewport decorator for all component stories
+- [ ] Test on-screen keyboard interaction for all form fields
+- [ ] Performance benchmark on simulated mobile CPU (4× slowdown) and 3G network
+
+#### P5.6 Mobile-Specific Success Metrics
+
+| Metric | Target | How Measured |
+|--------|--------|--------------|
+| **Touch Target Compliance** | 100% ≥ 44px | Automated scan via `useTouchTarget` |
+| **Mobile Lighthouse Score** | ≥ 90 (Performance, Accessibility) | Lighthouse CI on mobile preset |
+| **First Contentful Paint (Mobile 3G)** | < 1.5s | Lighthouse / Web Vitals |
+| **Time to Interactive (Mobile 3G)** | < 3.5s | Lighthouse / Web Vitals |
+| **Responsive Breakpoint Coverage** | All 13+ views × 3 breakpoints | Playwright viewport tests |
+| **Mobile Gesture Coverage** | Swipe, pinch, long-press in all applicable views | E2E gesture tests |
+| **PWA Install Success** | Manifest + service worker valid | Lighthouse PWA audit |
+
+---
+
 ## 🔮 Future Vision (Deferred)
 
 > The following items are **not** in the current sprint. They will be re-evaluated once P1–P4 are substantially complete.
@@ -326,6 +514,9 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 | **WCAG AA Compliance** | Full Console pages | Full Console pages | axe-core audit |
 | **CLI Commands Working** | 11 | 11 (all verified) | `objectui doctor` |
 | **TODO/FIXME Count** | 0 files | 0 | Grep `TODO\|FIXME\|HACK` |
+| **Mobile Responsive Views** | Partial (2/13) | 13/13 (100%) | Playwright mobile tests |
+| **Mobile Lighthouse Score** | Not measured | ≥ 90 | Lighthouse CI mobile preset |
+| **Touch Target Compliance** | Not measured | 100% ≥ 44px | Automated touch target scan |
 
 ### DX Success Criteria
 - [x] New developer can `git clone` → `pnpm install` → `pnpm dev` → see Console in < 5 minutes
@@ -339,6 +530,13 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 - [x] Grid view handles 10,000+ records without jank (< 100ms interaction latency)
 - [x] Full keyboard navigation for all Console workflows (no mouse required)
 
+### Mobile UX Success Criteria
+- [ ] All 13+ views render correctly at 375px viewport (iPhone SE)
+- [ ] Touch targets ≥ 44px for all interactive elements
+- [ ] Console Lighthouse mobile score ≥ 90 (Performance + Accessibility)
+- [ ] All views support horizontal scroll or responsive stacking on mobile
+- [ ] Swipe gestures work for navigation, Kanban columns, and Calendar days
+
 ---
 
 ## ⚠️ Risk Management
@@ -352,6 +550,7 @@ All 4 phases complete across 5 designers (Page, View, DataModel, Process, Report
 | **Component API inconsistency** | Audit checklist, automated prop-type validation, Storybook as source of truth |
 | **Documentation drift** | TSDoc generation from source, Storybook stories alongside code, link checker CI |
 | **Accessibility regression** | axe-core tests on full Console pages (not just primitives), WCAG AA CI check |
+| **Mobile responsiveness regression** | Playwright mobile viewport tests, Lighthouse CI mobile preset, touch target audit |
 
 ---