design-mobile-first · diff

git:20260821.2a41031 to git:20260912.33d48b1

1 added, 1 removed. Audit A to A.

---

name: design-mobile-first

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

**Degree of freedom: MIXED.** Pattern choice `[HIGH freedom]`; breakpoint,

viewport, and existing-hook inventory `[LOW freedom — run exactly]`.

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`.

## How to reason

1. **Survey** — breakpoints, viewport, existing mobile hooks

2. **Base** — mobile styles first (44px, safe-area)

3. **Enhance** — `sm:`/`md:`/`lg:` add up; they do not replace the base

4. **Device-check** — real phone, not only a resized desktop window

## Worked example

> **Survey:** Tailwind `sm/md/lg` exist; checkout CTA is `h-8`; no `safe-area-inset-bottom`.

> **Base:** `min-h-[44px]`, `pb-[env(safe-area-inset-bottom)]`, stacked fields, 16px inputs.

> **Enhance:** two-column names at `sm:`; table replaces cards at `md:`.

> **Device-check:** thumb reaches the CTA; iOS does not zoom on focus.

## Self-critique before reporting

- **Base is mobile** — primary layout is not `lg:`-only

- **44px + safe-area** — tap targets and notches were measured

- **Real device** — not emulator-or-resize only

- **Right owner** — linearized 1440 desktop → `audit-responsive`; hybrid native chrome → `enhance-capacitor-ui`

- ## CRITICAL: Check Existing First [LOW freedom — run exactly]

+ ## Check existing first [LOW freedom — run exactly]

**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 [HIGH freedom]

### 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 [LOW freedom — do not skip]

Touch ≥44px · thumb-zone CTAs · gestures with feedback · 60fps · no focus-zoom · safe-area · offline-graceful · real device (not emulator-only).

## 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