Responsive & Native-Feel Patterns

Mobile-first responsive design patterns, breakpoint system, touch-optimized interactions, and progressive web app considerations to deliver a native-quality experience across all devices.

Overview

MTC is built with a mobile-first philosophy using Tailwind CSS responsive utilities. The application uses TanStack Start with server-side rendering, which provides fast initial loads on mobile networks. The layout system adapts from single-column mobile views to multi-column desktop layouts using Tailwind's breakpoint prefixes (sm, md, lg, xl). The sidebar navigation collapses on mobile and is accessed via a hamburger menu with an overlay.

All interactive elements are designed with touch targets in mind. Buttons maintain minimum 44px touch targets, form inputs are appropriately sized for thumb interaction, and cards use generous padding for comfortable tapping. The shadcn/ui component library provides accessible, touch-friendly components out of the box. Custom ScrollArea components ensure consistent scrollbar behavior across platforms.

The platform uses motion/react (Framer Motion) for animations that respect the user's reduced-motion preference via the prefers-reduced-motion media query. Future PWA features will enable home screen installation, offline caching of viewed content, and push notification support through service workers. The Cloudflare Workers deployment provides edge-level performance globally.

Breakpoint System

Breakpoint Min-Width Typical Device Layout Behavior
default 0px Mobile phones Single column, stacked layout, hamburger menu
sm: 640px Large phones, small tablets 2-column grids begin, wider cards
md: 768px Tablets Sidebar visible (collapsed), 2-column pricing
lg: 1024px Laptops Sidebar expanded, 3-column grids
xl: 1280px Desktops Full layout, 4-column pricing grid

Layout Patterns

Page Width Standards

  • max-w-6xl — List/grid pages
  • max-w-4xl — Detail/form pages
  • max-w-3xl — Settings/narrow
  • max-w-2xl — Feed pages

Sidebar Navigation

  • Mobile: Hidden, accessed via hamburger
  • Tablet: Collapsed icon-only sidebar
  • Desktop: Full expanded sidebar
  • Overlay backdrop on mobile open

Grid Responsiveness

  • Connections: 1 → 2 → 3 columns
  • Programs: 1 → 2 → 3 columns
  • Pricing: 1 → 2 → 4 columns
  • Status cards: 1 → 2 → 3 columns

Content Stacking

  • Session cards: full-width stacked
  • Feed: single-column centered
  • Forms: single-column with labels
  • Stats bar: horizontal scroll on mobile

Spacing System

  • Page padding: p-6 (24px)
  • Section gaps: space-y-6
  • Card gaps: gap-4
  • All auto-centered: mx-auto

Scrolling

  • Always use ScrollArea component
  • Never raw overflow-auto/scroll
  • Horizontal scroll: add ScrollBar
  • overflow-hidden OK for clipping

User Stories

As a mobile user, I want the app to be fully functional on my phone so that I can manage my training on the go.

As a user, I want touch-friendly buttons and inputs so that I can easily interact with the app using my fingers.

As a user on a slow connection, I want fast initial page loads so that I do not have to wait for the app to become usable.

As a user, I want the navigation to adapt to my screen size so that I always have access to all features.

As a user with motion sensitivity, I want animations to respect my system preferences so that the app does not cause discomfort.

As a mobile user, I want to install the app on my home screen so that I can access it like a native app.

Touch Interaction Guidelines

Touch Targets

  • Minimum target size: 44px x 44px (WCAG 2.5.5)
  • Buttons use adequate padding for thumb reach
  • Card action buttons span full width on mobile
  • Navigation items have generous hit areas
  • Form inputs are minimum 40px height

Gesture Support

  • Tap: Primary action for buttons and links
  • Scroll: Natural scrolling via ScrollArea
  • Drag-and-drop: Onboarding goal reordering (via dnd-kit)
  • Pull-to-refresh: Planned for feed and session lists
  • Swipe: Planned for card dismissal and tab navigation

Performance Optimizations

Server-Side Rendering

TanStack Start provides SSR with streaming, delivering HTML before JavaScript loads. Route loaders pre-fetch data to eliminate client-side loading spinners.

Edge Deployment

Cloudflare Workers deploy code to 300+ edge locations globally, ensuring sub-100ms TTFB for users worldwide.

Optimistic Updates

Every mutation instantly updates the UI cache before server round-trip, providing zero-latency interaction feedback.

React Compiler

React 19 compiler auto-memoizes components and hooks, reducing unnecessary re-renders without manual optimization.

Image Optimization

Cloudflare Image Resizing for responsive images. Avatar fallbacks prevent layout shift. Lazy loading for off-screen content.

Font Loading

Google Fonts with preconnect hints and display=swap. Three typefaces: DM Sans (body), Syne (display), JetBrains Mono (code).

Theme Support

Dark Mode

Default theme. Deep blacks with zinc grays. Cyan-to-teal gradient accents. Optimized for OLED screens with true black backgrounds.

Light Mode

White backgrounds with slate grays. Maintains the same cyan/teal accent palette. Card borders for visual separation.

System Mode

Follows the operating system preference via prefers-color-scheme media query. Automatically switches between dark and light.

Acceptance Criteria

  • All pages are fully responsive from 320px to 2560px viewport widths
  • Sidebar collapses to hamburger menu on mobile with overlay backdrop
  • Grid layouts adapt column count based on viewport breakpoints
  • Touch targets meet 44px minimum for WCAG compliance
  • Dark/light/system theme toggle works correctly across all pages
  • Animations respect prefers-reduced-motion system preference
  • SSR delivers rendered HTML before JavaScript hydrates
  • ScrollArea component used for all scrollable containers (never raw overflow)
  • PWA manifest and service worker for home screen installation are not yet set up
  • Offline caching and background sync are not yet implemented
  • Pull-to-refresh and swipe gestures are not yet implemented
  • Bottom navigation bar for mobile app-like experience is not yet built

Key Responsive Components

AppSidebar Collapsible sidebar with hamburger trigger, overlay, and collapse persistence
AppHeader Responsive header with breadcrumbs, search, and theme toggle
ScrollArea Custom scrollbar component used for all scrollable containers
Card Grid Responsive grid: grid gap-4 sm:grid-cols-2 lg:grid-cols-3
Tabs Horizontal scrollable tabs on narrow screens, flex wrap on wider
Dialog / Sheet Full-screen on mobile, centered modal on desktop

Current Status

Built

Responsive Layouts

All pages use Tailwind responsive utilities with mobile-first approach and standard max-width patterns.

Built

Sidebar Navigation

Collapsible sidebar with mobile hamburger menu, overlay, and localStorage state persistence.

Built

Theme System

Dark/light/system theme with CSS variables, no FOUC, and persistence via localStorage.

Built

SSR + Edge

TanStack Start SSR on Cloudflare Workers edge network for fast global performance.

Planned

PWA Support

Web app manifest, service worker, home screen installation, and offline caching.

Planned

Mobile Navigation

Bottom tab bar for mobile, pull-to-refresh, swipe gestures, and app-like navigation patterns.