# Home Screen Web App Icon

How to give a web page a custom icon when added to the iPhone/Android home screen as a PWA.

## Meta Tags

Add these to every HTML page in the flow:

```html
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="mobile-web-app-capable" content="yes">
<meta name="theme-color" content="#121212">

<!-- iOS home screen icon -->
<link rel="apple-touch-icon" href="icon.jpg">
<!-- Android/favicon -->
<link rel="icon" type="image/jpeg" href="icon.jpg">
```

## Icon Specs

- **Format**: JPEG or PNG (iOS prefers JPEG for compression)
- **Size**: 180x180px minimum (iOS generates smaller sizes automatically)
- **Style**: Use the app's actual logo or brand mark
- **Background**: iOS adds rounded corners and gloss automatically; no need to bake them in

## Workflow

1. Get the icon image from the user or find the app's official logo
2. Copy it to the project directory alongside HTML files
3. Add the `<link>` tags to every HTML page (login, dashboard, detail, etc.)
4. When user adds to home screen, the icon appears instead of a screenshot thumbnail

## Pitfall: Icon Not Showing

If the icon doesn't appear after adding to home screen:
- **Cache issue**: Delete the home screen icon and re-add it
- **Wrong path**: Ensure the `href` path is correct relative to each HTML file
- **Format**: Try PNG instead of JPEG if JPEG fails on some Android devices
- **HTTPS required**: iOS may not show custom icons on HTTP (use Tailscale Funnel)

## Example Directory

```
kbc-flow/
  index.html              (has <link rel="apple-touch-icon" href="kbc-icon.jpg">)
  home-dashboard.html     (has same link tag)
  account-overview.html   (has same link tag)
  transaction-detail.html (has same link tag)
  kbc-icon.jpg            (shared icon file)
  login-hero.jpg          (hero image for login page)
  sage-profile.jpg        (avatar image for account card)
```

## Replacing vs. Re-Adding

**Important**: Changing the icon file on disk does NOT update existing home screen icons. The user must:
1. Delete the old home screen icon
2. Re-add the page to home screen
3. The new icon will appear

There is no way to programmatically update an existing home screen icon from the web.