Mobile-First UX Optimization

Build touch-optimized, performant mobile experiences with proper viewport handling and responsive patterns.

When to Use

✅ USE this skill for:

Viewport issues (100vh problems, safe areas, notches) Touch target sizing and spacing Mobile navigation patterns (bottom nav, drawers, hamburger menus) Swipe gestures and pull-to-refresh Responsive breakpoint strategies Mobile performance optimization

❌ DO NOT use for:

Native app development → use react-native or swift-executor skills Desktop-only features → no skill needed, standard patterns apply General CSS/Tailwind questions → use Tailwind docs or web-design-expert PWA installation/service workers → use pwa-expert skill Core Principles Mobile-First Means Build Up, Not Down / ❌ ANTI-PATTERN: Desktop-first (scale down) / .card { width: 400px; } @media (max-width: 768px) { .card { width: 100%; } }

/ ✅ CORRECT: Mobile-first (scale up) / .card { width: 100%; } @media (min-width: 768px) { .card { width: 400px; } }

The 44px Rule

Apple's Human Interface Guidelines specify 44×44 points as minimum touch target. Google Material suggests 48×48dp.

// Touch-friendly button Tap me

// Touch-friendly link with adequate padding Link text

Viewport Handling The dvh Solution

Mobile browsers have dynamic toolbars. 100vh includes the URL bar, causing content to be cut off.

/ ❌ ANTI-PATTERN: Content hidden behind browser UI / .full-screen { height: 100vh; }

/ ✅ CORRECT: Responds to browser chrome / .full-screen { height: 100dvh; }

/ Fallback for older browsers / .full-screen { height: 100vh; height: 100dvh; }

Safe Area Insets (Notches & Home Indicators) / Handle iPhone notch and home indicator / .bottom-nav { padding-bottom: env(safe-area-inset-bottom, 0); }

.header { padding-top: env(safe-area-inset-top, 0); }

/ Full safe area padding / .safe-container { padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left); }

Required meta tag:

Tailwind Safe Area Classes // Custom Tailwind utilities (add to globals.css) @layer utilities { .pb-safe { padding-bottom: env(safe-area-inset-bottom); } .pt-safe { padding-top: env(safe-area-inset-top); } .h-screen-safe { height: calc(100dvh - env(safe-area-inset-top) - env(safe-area-inset-bottom)); } }

// Usage

Mobile Navigation Patterns Bottom Navigation (Recommended for Mobile) // components/BottomNav.tsx 'use client';

import { usePathname } from 'next/navigation'; import Link from 'next/link';

const navItems = [ { href: '/', icon: HomeIcon, label: 'Home' }, { href: '/meetings', icon: CalendarIcon, label: 'Meetings' }, { href: '/tools', icon: ToolsIcon, label: 'Tools' }, { href: '/my', icon: UserIcon, label: 'My Recovery' }, ];

export function BottomNav() { const pathname = usePathname();

return (

Slide-Out Drawer (Side Menu) 'use client';

import { useState, useEffect } from 'react'; import { createPortal } from 'react-dom';

interface DrawerProps { isOpen: boolean; onClose: () => void; children: React.ReactNode; }

export function Drawer({ isOpen, onClose, children }: DrawerProps) { // Prevent body scroll when open useEffect(() => { if (isOpen) { document.body.style.overflow = 'hidden'; } return () => { document.body.style.overflow = ''; }; }, [isOpen]);

// Close on escape useEffect(() => { const handleEscape = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); }; document.addEventListener('keydown', handleEscape); return () => document.removeEventListener('keydown', handleEscape); }, [onClose]);

if (!isOpen) return null;

return createPortal(

  {/* Drawer */}
  <div
    className="absolute left-0 top-0 h-full w-[280px] max-w-[80vw]
               bg-leather-900 shadow-xl transform transition-transform
               animate-slide-in-left"
    role="dialog"
    aria-modal="true"
  >
    <div className="h-full overflow-y-auto pt-safe pb-safe">
      {children}
    </div>
  </div>
</div>,
document.body