---
name: mobile-web-development
trigger: Use when building mobile-responsive web pages, replicating native app UIs in HTML/CSS, creating installable home screen web apps, or serving local pages to a phone for testing.
description: Build mobile-first HTML/CSS pages that mimic native apps.
---

# Mobile Web Development

## 1. Quick Start Checklist

- [ ] `meta viewport` with `viewport-fit=cover` and `user-scalable=no`
- [ ] Home screen meta tags (`apple-mobile-web-app-capable`, `mobile-web-app-capable`)
- [ ] `theme-color` matching the dark background
- [ ] `env(safe-area-inset-*)` padding for notched phones
- [ ] Dark mode color palette (`#121212` bg, `#1e1e1e` cards, `#fff` text, `#888` muted)
- [ ] Bottom nav or content padding for home indicator (`env(safe-area-inset-bottom)`)

## 2. Meta Tags (Copy-Paste)

```html
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="theme-color" content="#121212">
<meta name="mobile-web-app-capable" content="yes">
```

## 3. Safe Area Insets

Always add padding for the status bar and home indicator:

```css
body {
  padding-top: max(28px, env(safe-area-inset-top, 28px));
}
.container {
  padding-bottom: max(80px, env(safe-area-inset-bottom, 80px));
}
```

**Pitfall:** Without `viewport-fit=cover` in the viewport meta tag, `env(safe-area-inset-*)` returns `0px`.

## 4. Serving Pages from the Right Directory

When using Python's built-in HTTP server, **explicitly set the working directory** or pages will 404:

```bash
# Correct — serve from /home/thesage
python3 -m http.server 8765 --directory /home/thesage --bind 127.0.0.1
```

**Pitfall:** Running `python3 -m http.server` without `--directory` serves from the current shell directory (often `~` or a project subdir), causing 404s for files you just wrote.

## 5. Exposing to Phone via Tailscale Funnel

```bash
# Start local server first, then expose
sudo tailscale funnel --bg 8765
# URL will be https://<your-host>.tail<xxxx>.ts.net/
```

**Pitfall:** The funnel URL must point to the same port the local server listens on (e.g., `8765`).

## 6. Pull-to-Refresh in Home Screen Mode

When added to the home screen (no URL bar), users refresh by **pulling down from the top of the page** — just like native apps. No extra JavaScript needed; Safari/Chrome handle it automatically for standalone web apps.

## 7. Matching Native App Screenshots

To replicate a native app layout pixel-perfect:

1. **Take screenshots** of each screen you want to replicate
2. **Build one screen at a time** — start with the simplest (login, then list, then detail)
3. **Use the screenshot as a reference** — check spacing, font sizes, icon placement
4. **Bold labels + normal values** inside gray boxes: use `<span class="box-label">Label:</span> Value`
5. **Stack vertically** inside `.detail-box` with `<p class="line">` for each row
6. **Gray boxes** = `background: #1e1e1e; border-radius: 12px; padding: 16px;`
7. **Separate sections** outside the box = `.detail-group` with `.label` (small, muted) + `.value` (bold, white)

## 8. Multi-Page Flow Navigation

Use simple anchor links between pages:

```html
<a href="account-select.html" class="login-btn">Log in</a>
<a href="account-overview.html" class="account-card">
<a href="transaction-detail.html" class="tx-item">
```

Add back buttons with `←` or SVG chevrons.

## 9. Common Dark Mode Palette

| Element | Color |
|---------|-------|
| Page background | `#121212` |
| Card/box background | `#1e1e1e` |
| Primary text | `#ffffff` |
| Muted/secondary text | `#888888` |
| Border/divider | `#222222` or `#333333` |
| Accent (banking blue) | `#00a0e3` |
| Bottom nav inactive | `#666666` |
| Status bar background | `#000000` (black-translucent) |

## 10. Bottom Navigation Pattern

```css
.bottom-nav {
  position: fixed;
  bottom: 0; left: 0; right: 0;
  background: #121212;
  border-top: 1px solid #1e1e1e;
  display: flex;
  justify-content: space-around;
  padding: 8px 0 max(8px, env(safe-area-inset-bottom, 8px));
}
```

## References
- See `templates/transaction-detail.html` for a complete dark-mode banking detail page