Web App Manifest Framework Skill

A Claude Code skill for creating and configuring Progressive Web App manifests — covering manifest.json setup, icons, splash screens, display modes, and PWA installation behavior across browsers and platforms.

When to Use This Skill

Choose this skill when:

• Adding PWA capabilities to a web application
• Configuring manifest.json for app-like behavior
• Setting up app icons, splash screens, and theme colors
• Enabling "Add to Home Screen" functionality
• Configuring display modes (standalone, fullscreen, minimal-ui)
• Optimizing the PWA installation experience

Consider alternatives when:

• You need a native mobile app (use React Native, Flutter)
• You need background sync or push notifications (use a Service Worker skill)
• You need app store distribution (use a hybrid app framework)

Quick Start

Copy
# Create manifest file
touch public/manifest.json

# Link in HTML
# <link rel="manifest" href="/manifest.json" />

Copy
{
  "name": "My Application",
  "short_name": "MyApp",
  "description": "A powerful productivity application",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ],
  "screenshots": [
    { "src": "/screenshots/home.png", "sizes": "1280x720", "type": "image/png", "form_factor": "wide" },
    { "src": "/screenshots/mobile.png", "sizes": "750x1334", "type": "image/png", "form_factor": "narrow" }
  ]
}

Core Concepts

Display Modes

Mode	Behavior	Use Case
fullscreen	No browser UI, fills entire screen	Games, immersive media
standalone	App-like window, no URL bar	Most applications
minimal-ui	Minimal browser controls	Content-heavy apps
browser	Normal browser tab	Fallback

Required Icon Sizes

Size	Platform	Purpose
48x48	Android notifications	Notification icon
72x72	Android older devices	Home screen icon
96x96	Android, desktop	Home screen icon
144x144	Android	Splash screen
192x192	Android, Chrome	Home screen, splash
512x512	Android, Chrome	Splash screen, store listing
Maskable 512x512	Android adaptive	Adapts to device icon shape

Service Worker Registration

Copy
// Register service worker for PWA
if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/sw.js')
      .then(reg => console.log('SW registered:', reg.scope))
      .catch(err => console.error('SW registration failed:', err));
  });
}

// Prompt install
let deferredPrompt;
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  deferredPrompt = e;
  showInstallButton();
});

async function installApp() {
  if (!deferredPrompt) return;
  deferredPrompt.prompt();
  const { outcome } = await deferredPrompt.userChoice;
  console.log('Install outcome:', outcome);
  deferredPrompt = null;
}

Configuration

Parameter	Type	Default	Description
name	string	—	Full application name (required)
short_name	string	—	Name for home screen (max 12 chars)
start_url	string	"/"	URL opened when app launches
scope	string	"/"	URL scope of the PWA
display	string	"standalone"	Display mode
theme_color	string	—	Browser toolbar and status bar color
background_color	string	—	Splash screen background color
orientation	string	"any"	Screen orientation lock
categories	array	[]	App categories for store listings

Best Practices

1. Include both regular and maskable icons at 512x512 — maskable icons adapt to different device shapes (circle, squircle, etc.); without them, your icon may be awkwardly cropped on some Android devices.

2. Set theme_color to match your app's primary color — this colors the browser toolbar and system status bar when the app is installed, creating a polished, app-like appearance.

3. Use short_name under 12 characters — home screen launchers truncate long names; keep short_name concise and recognizable for the app icon label.

4. Add screenshots for richer install prompts — browsers show screenshots in the install prompt on supported platforms; include both wide (desktop) and narrow (mobile) screenshots.

5. Set start_url to "/?source=pwa" for analytics tracking — adding a query parameter lets you distinguish PWA users from browser users in your analytics.

Common Issues

Install prompt doesn't appear — Chrome requires HTTPS, a valid manifest, a registered service worker, and the user must visit the site at least twice with 5 minutes between visits. Test in Chrome DevTools Application panel.

Icons look blurry on high-DPI screens — Provide icons at multiple sizes (at least 192 and 512); the browser will choose the best match for the device's pixel density.

Background color flash during app launch — The background_color in the manifest is shown as a splash screen before the app loads. Match it to your app's actual background color to avoid a jarring flash.