git:20260717.94f726c to git:20260817.5b93a21

15 added, 2 removed. Audit A to A.

---

name: design-mobile-first

- description: Designs mobile-first responsive interfaces with touch optimization — breakpoint strategy, touch targets, safe areas, and gesture handling, enhanced progressively for larger screens. Use when the user mentions "mobile", "responsive", "touch", "PWA", "small screen", "tablet", "swipe", or "gesture", or when a UI looks desktop-only on a phone viewport.

+ description: >

+ Design mobile-first UIs: touch targets, safe areas, gestures, then enhance up.

+ Use when building for small screens, touch, swipe, PWA, or tablet. Linearized

+ desktop / responsive audit → audit-responsive.

license: MIT

---

# Mobile-First Design Skill

- Build interfaces that work beautifully on mobile devices first, then enhance for larger screens.

+ Build interfaces that work on mobile first, then enhance for larger screens.

+ **Not this skill:** a desktop that is a linearized phone (no max-width, stacked

+ at 1440, stretched buttons). That is `audit-responsive`.

## CRITICAL: Check Existing First

**Before ANY mobile optimization, verify:**

1. **Check existing breakpoints:**

```bash

cat tailwind.config.* | grep -A10 "screens\|breakpoints"

rg "sm:|md:|lg:|xl:" --type tsx | head -20

```

2. **Check for existing mobile patterns:**

```bash

rg "useMediaQuery|useBreakpoint|isMobile" --type ts --type tsx

ls -la src/hooks/use*Mobile* src/hooks/use*Responsive* 2>/dev/null

```

3. **Check viewport meta:**

```bash

rg "viewport" src/app/layout.tsx index.html

```

**Why:** Maintain consistent responsive patterns across the app.

## Mobile-First Principles

### 1. Design for Mobile First

```css

/* Base styles = mobile */

.card {

padding: 1rem;

font-size: 0.875rem;

}

/* Then enhance for larger screens */

@media (min-width: 640px) {

.card {

padding: 1.5rem;

font-size: 1rem;

}

/* Tailwind design-mobile-first */

```

### 2. Touch Targets (44px minimum)

```tsx

// Touch-friendly button

Tap me

</button>

// Touch-friendly list items

List item

</li>

// Icon buttons with proper touch area

<button

className="p-3 -m-3" // Negative margin extends touch area

aria-label="Menu"

</button>

```

### 3. Thumb-Friendly Zones

```tsx

// Bottom navigation for primary actions

</div>

</nav>

// Safe area padding for notched devices

.safe-area-pb {

padding-bottom: env(safe-area-inset-bottom);

}

```

## Responsive Patterns

### Mobile Navigation

```tsx

'use client'

import { useState } from 'react'

import { motion, AnimatePresence } from 'framer-motion'

export function MobileNav() {

const [isOpen, setIsOpen] = useState(false)

return (

<button

className="lg:hidden p-2"

onClick={() => setIsOpen(true)}

aria-label="Open menu"

</button>

{isOpen && (

{/* Backdrop */}

<motion.div

initial={{ opacity: 0 }}

animate={{ opacity: 1 }}

exit={{ opacity: 0 }}

className="fixed inset-0 bg-black/50 z-40 lg:hidden"

onClick={() => setIsOpen(false)}

{/* Drawer */}

<motion.div

initial={{ x: '-100%' }}

animate={{ x: 0 }}

exit={{ x: '-100%' }}

transition={{ type: 'spring', damping: 25, stiffness: 200 }}

className="fixed inset-y-0 left-0 w-[280px] bg-background z-50 lg:hidden"

<button

className="absolute top-4 right-4 p-2"

onClick={() => setIsOpen(false)}

</button>

{navItems.map((item) => (

key={item.href}

href={item.href}

className="block py-3 px-4 rounded-lg hover:bg-muted"

{item.label}

</a>

))}

</nav>

</div>

</motion.div>

</>

)}

</AnimatePresence>

</>

)

}

```

### Responsive Tables

```tsx

// Card-based layout on mobile, table on desktop

export function ResponsiveTable({ data }: { data: Item[] }) {

return (

{/* Mobile: Card layout */}

{data.map((item) => (

</div>

{item.description}

</div>

<span className="font-semibold">{item.amount}</span>

<Badge>{item.status}</Badge>

</div>

))}

</div>

{/* Desktop: Traditional table */}

<thead>

<th className="text-left py-3">Amount</th>

<th className="text-left py-3">Status</th>

</tr>

</thead>

<tbody>

{data.map((item) => (

<td className="py-3">{item.amount}</td>

<td className="py-3"><Badge>{item.status}</Badge></td>

</tr>

))}

</tbody>

</table>

</>

)

}

```

### Responsive Grid

```tsx

// Fluid grid that adapts to screen size

{items.map((item) => (

<Card key={item.id}>{item.content}</Card>

))}

</div>

// Auto-fit grid (items wrap naturally)

{items.map((item) => (

<Card key={item.id}>{item.content}</Card>

))}

</div>

```

## Touch Gestures

### Swipe to Delete

```tsx

'use client'

import { motion, useMotionValue, useTransform, PanInfo } from 'framer-motion'

export function SwipeableItem({ onDelete, children }: SwipeableItemProps) {

const x = useMotionValue(0)

const background = useTransform(

[-100, 0],

['rgb(239 68 68)', 'rgb(255 255 255)']

)

const handleDragEnd = (_: any, info: PanInfo) => {

if (info.offset.x < -100) {

onDelete()

}

return (

<motion.div style={{ background }} className="relative overflow-hidden rounded-lg">

<motion.div

drag="x"

dragConstraints={{ left: -100, right: 0 }}

onDragEnd={handleDragEnd}

style={{ x }}

className="bg-background p-4"

{children}

</motion.div>

</div>

</motion.div>

)

}

```

### Pull to Refresh

```tsx

'use client'

import { useState, useRef } from 'react'

import { motion, useMotionValue, useTransform } from 'framer-motion'

export function PullToRefresh({ onRefresh, children }: PullToRefreshProps) {

const [isRefreshing, setIsRefreshing] = useState(false)

const y = useMotionValue(0)

const opacity = useTransform(y, [0, 60], [0, 1])

const scale = useTransform(y, [0, 60], [0.5, 1])

const handleDragEnd = async () => {

if (y.get() > 60) {

setIsRefreshing(true)

await onRefresh()

setIsRefreshing(false)

}

return (

<motion.div

style={{ opacity, scale }}

className="flex justify-center py-4"

</motion.div>

<motion.div

drag="y"

dragConstraints={{ top: 0, bottom: 0 }}

dragElastic={0.5}

onDragEnd={handleDragEnd}

style={{ y }}

{children}

</motion.div>

</div>

)

}

```

## Mobile-Specific Components

### Bottom Sheet

```tsx

'use client'

import { motion, useDragControls, PanInfo } from 'framer-motion'

export function BottomSheet({ isOpen, onClose, children }: BottomSheetProps) {

const controls = useDragControls()

const handleDragEnd = (_: any, info: PanInfo) => {

if (info.velocity.y > 500 || info.offset.y > 200) {

onClose()

}

if (!isOpen) return null

return (

<motion.div

initial={{ opacity: 0 }}

animate={{ opacity: 1 }}

exit={{ opacity: 0 }}

className="fixed inset-0 bg-black/50 z-40"

onClick={onClose}

<motion.div

initial={{ y: '100%' }}

animate={{ y: 0 }}

exit={{ y: '100%' }}

drag="y"

dragControls={controls}

dragConstraints={{ top: 0 }}

dragElastic={0.2}

onDragEnd={handleDragEnd}

className="fixed bottom-0 left-0 right-0 bg-background rounded-t-xl z-50 max-h-[90vh] overflow-hidden"

{/* Drag handle */}

<div

className="flex justify-center py-3 cursor-grab active:cursor-grabbing"

onPointerDown={(e) => controls.start(e)}

</div>

{children}

</div>

</motion.div>

</>

)

}

```

### Mobile-Optimized Forms

```tsx

// Stack form fields vertically on mobile

<Label htmlFor="firstName">First Name</Label>

<Input

id="firstName"

// Larger touch targets

className="h-12 text-base"

// Prevent iOS zoom on focus

style={{ fontSize: '16px' }}

</div>

<Input

id="lastName"

className="h-12 text-base"

style={{ fontSize: '16px' }}

</div>

{/* Full-width button on mobile */}

Submit

</Button>

</form>

```

## PWA Features

### Viewport & Meta Tags

```tsx

// app/layout.tsx

export const metadata = {

viewport: {

width: 'device-width',

initialScale: 1,

maximumScale: 1, // Prevents zoom on input focus

userScalable: false,

viewportFit: 'cover', // For notched devices

appleWebApp: {

capable: true,

statusBarStyle: 'default',

title: 'My App',

}

```

### Install Prompt

```tsx

'use client'

import { useEffect, useState } from 'react'

export function InstallPrompt() {

const [deferredPrompt, setDeferredPrompt] = useState<any>(null)

useEffect(() => {

const handler = (e: Event) => {

e.preventDefault()

setDeferredPrompt(e)

}

window.addEventListener('beforeinstallprompt', handler)

return () => window.removeEventListener('beforeinstallprompt', handler)

}, [])

if (!deferredPrompt) return null

const handleInstall = async () => {

deferredPrompt.prompt()

const { outcome } = await deferredPrompt.userChoice

if (outcome === 'accepted') {

setDeferredPrompt(null)

}

return (

<p className="font-medium">Install our app</p>

<p className="text-sm text-muted-foreground">Get quick access from your home screen</p>

<Button onClick={handleInstall}>Install</Button>

<Button variant="ghost" onClick={() => setDeferredPrompt(null)}>

Not now

</Button>

</div>

)

}

```

## Validation

After implementing mobile features:

1. **Touch targets** → All interactive elements ≥44px

2. **Thumb zones** → Primary actions reachable with thumb

3. **Gestures** → Natural, discoverable, with visual feedback

4. **Performance** → 60fps scrolling, no jank

5. **Forms** → No zoom on focus, appropriate keyboards

6. **Safe areas** → Content respects notches and home indicators

7. **Offline** → Graceful handling when offline

8. **Real device test** → Test on actual phones, not just emulators

+ ## Related

+ - `audit-responsive` — unstack desktop; layout/IA at 375 / 768 / 1440

+ - `enhance-capacitor-ui` — hybrid web + native form-factor axes

+ - `design-frontend` — new visual surfaces

+ - `audit-performance` — mobile perf budgets