From 9917d24cf0d77fb3ff221e6c3903cd3034fed1a3 Mon Sep 17 00:00:00 2001
From: medking82 <19301787+medking82@users.noreply.github.com>
Date: Wed, 22 Jul 2026 10:06:27 +0800
Subject: [PATCH] feat(apple-design): add iPhone Home Screen profile
---
README.md | 2 +-
.../apple-home-screen-web-app-profile.md | 241 +++++++++++++++++
skills/apple-design/SKILL.md | 9 +-
.../references/ios-home-screen-web-app.md | 247 ++++++++++++++++++
4 files changed, 497 insertions(+), 2 deletions(-)
create mode 100644 docs/plans/apple-home-screen-web-app-profile.md
create mode 100644 skills/apple-design/references/ios-home-screen-web-app.md
diff --git a/README.md b/README.md
index 27689e589..e135cbeab 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ This is your shortcut to great interfaces. A shortcut to stand out in a sea of s
- **[improve-animations](./skills/improve-animations/SKILL.md)** — Audit all the animations in your codebase and get prioritized, self-contained plans that any agent can execute.
- **[find-animation-opportunities](./skills/find-animation-opportunities/SKILL.md)** — Search your UI for places that would genuinely benefit from motion, while also telling you what not to animate.
- **[animation-vocabulary](./skills/animation-vocabulary/SKILL.md)** — Get better animations from an AI by telling it exactly what you want by using the right words.
-- **[apple-design](./skills/apple-design/SKILL.md)** — Apple's principles for interface design and fluid motion, distilled from their WWDC design talks and translated for the web.
+- **[apple-design](./skills/apple-design/SKILL.md)** — Apple's interface and fluid-motion principles for the web, including iPhone Home Screen and standalone PWA experience guidance.
- **[pick-ui-library](./skills/pick-ui-library/SKILL.md)** — Have your agent pick the right library for the task based on libraries I use and trust, instead of letting AI hand-roll a toast component or install an abandoned package.
### Improve animations
diff --git a/docs/plans/apple-home-screen-web-app-profile.md b/docs/plans/apple-home-screen-web-app-profile.md
new file mode 100644
index 000000000..f1e853c6b
--- /dev/null
+++ b/docs/plans/apple-home-screen-web-app-profile.md
@@ -0,0 +1,241 @@
+# Apple Home Screen web-app experience profile
+
+## Intent
+
+Extend `apple-design` with an iOS-focused profile for mobile web apps that people add to
+the Home Screen. The profile should help an agent design and implement a web app that remains
+sound in a browser and feels coherent, responsive, and trustworthy when launched in standalone
+mode, without pretending that a PWA has every native-app capability.
+
+The primary target is a standards-based mobile Web/PWA experience on iPhone. Native SwiftUI,
+UIKit, App Store packaging, and a macOS profile are separate future decisions.
+
+When a user asks for a change rather than advice, the skill must be able to inspect the target
+web app's existing framework and implement the PWA/app-shell capability in that app. This
+repository changes only the reusable skill guidance; applying it to Johorindustry or another
+product remains a separate frozen changeset in that product repository.
+
+## Context map
+
+- Request entry point: prompts such as “make this mobile site feel like an app,” “optimize this
+ PWA for Add to Home Screen,” “make the installed web app feel native on iPhone,” or requests
+ involving standalone mode, safe areas, app icons, offline continuity, push, or badging.
+- Skill routing: `skills/apple-design/SKILL.md` frontmatter decides whether the skill loads. Its
+ body currently routes no platform-specific references and is primarily a fluid-motion guide.
+- New knowledge surface: `skills/apple-design/references/ios-home-screen-web-app.md`, loaded only
+ for mobile web/PWA/Home Screen work.
+- Shared behavior: the existing response, direct-manipulation, interruptibility, material,
+ typography, accessibility, and design-principle guidance remains authoritative for motion and
+ craft. The new profile adds product-shell and lifecycle guidance; it must not duplicate the
+ existing motion reference.
+- Canonical persistence: the complete `skills/apple-design/` tree in this repository. The existing
+ updater already manifests and copies the complete tree, so a reference file needs no updater
+ change.
+- Downstream consumers: future Codex and Claude installations after an explicit digest-bound
+ Apply. Publishing this repository alone does not update installed snapshots.
+- External platform dependencies: iOS/iPadOS Home Screen web-app behavior, Web App Manifest,
+ Service Workers, safe-area environment variables, Web Push, Notifications, and Badging APIs.
+ Guidance must use feature detection and progressive enhancement rather than version sniffing.
+- Relevant operational boundary: the installed Home Screen app is still web content with browser
+ storage, network, lifecycle, and API constraints. The profile must preserve a usable browser
+ experience and must not promise native-only behavior.
+- Rollback: before publication, revert only the allowed documentation/skill files. After
+ publication, installed copies remain unchanged until a human accepts the new tree digest and
+ explicitly runs Apply.
+- Motivating brownfield evidence: a read-only audit of Johorindustry at commit `d7476533` found
+ mobile safe-area and viewport fixes distributed across leaf components, while no manifest,
+ Service Worker, Home Screen identity, or shared standalone lifecycle was present. Its retired
+ `/johorpro` layout still owns viewport/theme fixes even though the route immediately redirects
+ into `/data-entry/johorpro`, demonstrating why the profile must trace the live route and shared
+ shell before adding local patches. These product-specific details are evidence, not content to
+ copy into the general skill.
+
+## Evidence and platform facts
+
+- WebKit states that iOS/iPadOS 26 opens every site added to the Home Screen as a web app by
+ default, while the user can choose to add a browser bookmark instead. A manifest remains useful
+ for identity, icons, and app configuration.
+
+- On earlier supported iOS/iPadOS versions, `display: standalone` or `fullscreen` in a manifest
+ produces the standalone Home Screen experience. Home Screen web apps appear separately in the
+ App Switcher. Manifest `id`, Web Push, and Badging are supported on applicable versions.
+
+- A Service Worker is not an iOS installability requirement, but WebKit identifies it as an
+ important enhancement. The skill should require a deliberate offline/update strategy when the
+ product needs continuity, not claim that installation itself depends on a Service Worker.
+- Apple’s layout guidance requires respect for safe areas and hardware/system features such as
+ rounded corners and Dynamic Island.
+
+- Apple’s current materials guidance confines Liquid Glass primarily to the functional layer of
+ controls and navigation and warns against using it throughout the content layer.
+
+
+## Observed gaps
+
+1. The `apple-design` description does not mention PWA, Add to Home Screen, standalone mobile web
+ apps, safe areas, app identity, offline continuity, or install-specific capabilities, so the
+ skill may not trigger for the target request.
+2. The skill begins with motion rather than deciding the product surface and display mode.
+3. It has no contract for browser mode versus standalone mode, launch/resume, navigation without
+ browser chrome, offline/error/update states, install education, or notification permission.
+4. Its material guidance can be read as encouragement to make all bars and sheets translucent;
+ the Home Screen profile needs the stricter functional-layer boundary from current HIG guidance.
+5. It has no Home Screen acceptance checklist or explicit anti-patterns for “native cosplay.”
+6. It does not require an agent to locate the live route, root metadata, authentication boundary,
+ shared navigation shell, update coordinator, or storage owner before editing. Without that map,
+ viewport and safe-area fixes can land in a retired route or be repeated inconsistently in leaf
+ components.
+
+## Required behavior
+
+### Trigger and routing
+
+1. Expand the `apple-design` frontmatter description just enough to trigger for mobile web apps,
+ PWAs, Add to Home Screen, standalone mode, and app-like iPhone experience. Preserve all existing
+ motion, typography, material, and accessibility triggers.
+2. Add a short platform-profile router near the start of `SKILL.md`. For a mobile Web/PWA/Home
+ Screen request, require reading `references/ios-home-screen-web-app.md` before proposing or
+ implementing the interface.
+3. Do not load the Home Screen reference for a motion-only request with no app-shell or mobile-PWA
+ concern.
+
+### Home Screen experience contract
+
+4. Require progressive enhancement: core tasks must work in a normal browser; standalone mode may
+ refine navigation, chrome, safe-area layout, launch behavior, and supported OS integrations.
+5. Cover app identity and launch configuration: manifest `id`, `name`/`short_name`, `start_url`,
+ `scope`, `display`, theme/background colors, and suitable icons. Note that `apple-touch-icon`
+ takes precedence over manifest icons on relevant Safari/iOS versions.
+6. Require feature detection for standalone display, safe-area support, Service Workers,
+ Notifications, Push, and Badging. Never branch primarily on a parsed iOS version.
+7. Define a complete shell without browser chrome: visible wayfinding and back/close affordances,
+ stable top-level navigation, deep-link-safe history, no dead ends, and preservation of user
+ context across relaunch where appropriate.
+8. Respect `env(safe-area-inset-*)`, status/navigation areas, device rotation, the software
+ keyboard, system edge gestures, and reachable primary actions. Do not place critical controls
+ under the home indicator, sensor housing, or gesture zones.
+9. Specify touch-first behavior: adequate hit areas, immediate pressed feedback, restrained
+ gestures with visible alternatives, native-feeling scroll, no accidental text selection, and
+ no custom gesture that steals a system navigation gesture without a compelling reason.
+10. Require explicit loading, empty, offline, reconnecting, error, and update-ready states. Preserve
+ unsent user work when practical; never surprise-reload merely because a new Service Worker is
+ available.
+11. Treat install education, notification permission, push, and badging as earned capabilities.
+ Ask in response to understandable user intent, explain the value, accept refusal, and avoid
+ badges or notifications that do not convey timely utility.
+12. Apply Liquid Glass/translucency only to a restrained functional layer. Keep content readable
+ and structurally clear with standard surfaces; Apple-like design must not reduce to blur,
+ oversized corner radii, or copied system chrome.
+13. Preserve accessibility across Dynamic Type-like text scaling, reduced motion, reduced
+ transparency, increased contrast, screen readers, external keyboards, and orientation changes.
+
+### Output contract
+
+14. When using this profile, identify the tested contexts: browser mode, installed standalone
+ mode, online/offline transition, relaunch, rotation, keyboard-open state, and applicable
+ accessibility preferences.
+15. Separate required baseline behavior from optional enhancements such as push, badging, wake
+ lock, or orientation lock. Recommend only enhancements supported by the product’s actual need.
+16. Include a compact Home Screen readiness checklist in the reference so an agent can audit an
+ implementation without inventing new criteria.
+
+### Target-app implementation contract
+
+17. Distinguish the user's requested mode: audit/report requests produce findings only; build or
+ change requests implement the smallest complete capability in the target web app. Do not stop
+ at generic advice when implementation is requested and authorized.
+18. Before editing a target app, trace the live host and route through middleware/rewrites, root
+ metadata, nested layouts, authentication redirects, navigation/history shell, global fixed
+ controls, storage, network state, and update behavior. Do not patch a legacy or redirect-only
+ route simply because its name looks canonical.
+19. Prefer a few route-aware choke points over scattered page fixes. Establish explicit owners for:
+ app identity/manifest, viewport and theme/status integration, standalone detection, safe-area
+ tokens, navigation/history, service-worker lifecycle, offline/reconnect state, and update UX.
+20. Adapt to the target framework's native conventions. For example, use framework metadata and
+ route APIs where they exist, preserve the existing router/auth/data model, and add only the
+ files required by that framework. Do not force a generic PWA template over a brownfield app.
+21. Treat leaf-level safe-area values as consumers of the shell contract. Audit every fixed,
+ sticky, draggable, fullscreen, toast/banner, modal/sheet, and keyboard-adjacent surface; ensure
+ the shared header, tab/navigation bars, floating controls, and update prompts obey the same
+ insets as feature components.
+22. Preserve useful existing behavior such as non-blocking update prompts, dirty-state guards,
+ durable session choices, and feature-specific offline fallbacks. Appification must integrate
+ them rather than replacing them with a second lifecycle system.
+23. Keep product code and shared-skill development in separate changesets and reviews. Findings
+ from one product may sharpen the generic profile, but product names, routes, tokens, auth
+ assumptions, and UI branding must not leak into the reusable skill.
+
+## Allowed changes
+
+- `docs/plans/apple-home-screen-web-app-profile.md`
+- `skills/apple-design/SKILL.md`
+- `skills/apple-design/references/ios-home-screen-web-app.md`
+- `README.md` only to update the existing one-line `apple-design` description if the final skill
+ scope would otherwise be misleading
+
+## Non-goals and do-not-touch boundaries
+
+- Do not add a top-level `ios`, `ios-macos`, or macOS skill in this changeset.
+- Do not add native SwiftUI, UIKit, AppKit, Xcode, signing, App Store, or packaging guidance.
+- Do not build or modify an actual product PWA, manifest, Service Worker, icon, screenshot, or
+ application asset in this repository changeset. The finished skill may implement those artifacts
+ later when a user invokes it for an authorized target-app change.
+- Do not change the updater, scheduler, tests for the updater, peer-review configuration, other
+ skills, installed user-scoped skills, or the upstream repository.
+- Do not add scripts, templates, `agents/openai.yaml`, README files inside the skill, or speculative
+ configuration.
+- Do not promise platform parity, guaranteed offline behavior, background execution, silent push,
+ or native APIs that the web platform does not provide.
+- Do not automatically sync upstream, Apply the skill, install it, run dogfood, deploy, resume,
+ rollback, purge memory, or clean historical worktrees.
+
+## Compatibility, security, and availability constraints
+
+- Prefer current standards and feature detection; mention legacy Apple meta tags only as a
+ compatibility fallback, not the primary model.
+- Never recommend requesting notification permission on first launch or without direct user intent.
+- Keep offline caches and retained drafts bounded and privacy-conscious; do not imply that sensitive
+ data should be cached by default.
+- Treat external links and OAuth/payment handoffs as lifecycle transitions that must return people
+ to a coherent app state; detailed auth/payment implementation is outside scope.
+- Preserve the existing skill name and relative install path so current updater validation and
+ consumers remain compatible.
+
+## Verification
+
+Targeted checks after implementation:
+
+1. Run the skill-creator `quick_validate.py` against `skills/apple-design`.
+2. Parse frontmatter and confirm `name: apple-design` remains unchanged.
+3. Confirm every new relative reference from `SKILL.md` exists and that the profile is one level
+ below the skill, with no duplicate copy of the existing motion guidance.
+4. Check the profile against four static scenarios:
+ - a mobile site that should remain excellent without installation;
+ - an installed iPhone Home Screen app launched without browser chrome;
+ - a temporary offline/reconnect/update transition with unsent work;
+ - a brownfield app whose named legacy route redirects into a different live shell, ensuring the
+ agent maps the live route and shared choke points before editing;
+ - a motion-only request that should continue using the current core without loading PWA detail.
+5. Confirm the documented checklist covers browser/standalone, safe areas, navigation, keyboard,
+ offline/error/update, accessibility, and permission timing.
+6. Run `git diff --check` and confirm the frozen diff contains only allowed files.
+
+No full repository test, updater test, live Home Screen dogfood, installed-skill Apply, or deployment
+is authorized by this plan. Any of those requires separate user authorization.
+
+## Review, delivery, and rollback
+
+- Risk: medium. The changes are documentation-only but alter a shared skill’s trigger and guidance
+ for future generated interfaces.
+- Base commit: `abaf55561806c84dd09e38fbcddc974f6aab50d5`.
+- Run at most one plan-review round, only after explicit user authorization. Failure, timeout, or
+ disagreement stops the workflow; do not retry or resubmit automatically.
+- After implementation and targeted checks, freeze the allowed diff and run one formal diff-review
+ process only when explicitly authorized. Authorized remediation may remain in that same review
+ run; do not start an independent second review automatically.
+- This repository has no `.sop/workflow.json`; commit, push, installed-skill Apply, and other
+ delivery actions remain manual and separately authorized.
+- Rollback is limited to the allowed files on this branch. Never rewrite `main` or mutate installed
+ skills as part of rollback.
+
+
diff --git a/skills/apple-design/SKILL.md b/skills/apple-design/SKILL.md
index 66f56807c..7896dfc7c 100644
--- a/skills/apple-design/SKILL.md
+++ b/skills/apple-design/SKILL.md
@@ -1,6 +1,6 @@
---
name: apple-design
-description: Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.
+description: Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography, reduced-motion, Apple-style design foundations, or mobile web apps and PWAs intended for Add to Home Screen, standalone mode, safe-area-aware app shells, and an app-like iPhone experience.
---
# Apple Design
@@ -9,6 +9,13 @@ How Apple builds interfaces that stop feeling like a computer and start feeling
The through-line: **an interface feels alive when motion starts from the current on-screen value, inherits the user's velocity, projects momentum forward, and can be grabbed and reversed at any instant.** Springs are the tool that makes all of this natural, because they are inherently interruptible and velocity-aware.
+## Platform profiles
+
+For a mobile Web/PWA, Add to Home Screen, standalone-mode, or iPhone app-shell request, read
+[`references/ios-home-screen-web-app.md`](references/ios-home-screen-web-app.md) before proposing
+or implementing changes. Keep using this core guidance for motion and craft. Do not load the
+profile for a motion-only request with no mobile app-shell or PWA concern.
+
## The Core Idea
> "When we align the interface to the way we think and move, something magical happens — it stops feeling like a computer and starts feeling like a seamless extension of us."
diff --git a/skills/apple-design/references/ios-home-screen-web-app.md b/skills/apple-design/references/ios-home-screen-web-app.md
new file mode 100644
index 000000000..f14bc77c2
--- /dev/null
+++ b/skills/apple-design/references/ios-home-screen-web-app.md
@@ -0,0 +1,247 @@
+# iPhone Home Screen web apps
+
+Use this profile for mobile web apps that should remain excellent in a browser and feel complete
+when launched from an iPhone Home Screen. Treat “app-like” as a product-shell and lifecycle
+quality bar, not permission to imitate native chrome or promise native capabilities.
+
+## Contents
+
+- [Start with the requested mode](#start-with-the-requested-mode)
+- [Map the live app before editing](#map-the-live-app-before-editing)
+- [Preserve the browser baseline](#preserve-the-browser-baseline)
+- [Define identity and launch behavior](#define-identity-and-launch-behavior)
+- [Build a complete shell without browser chrome](#build-a-complete-shell-without-browser-chrome)
+- [Own the viewport, safe areas, rotation, and keyboard](#own-the-viewport-safe-areas-rotation-and-keyboard)
+- [Make touch and scrolling feel direct](#make-touch-and-scrolling-feel-direct)
+- [Design lifecycle, offline, and update states](#design-lifecycle-offline-and-update-states)
+- [Earn optional capabilities](#earn-optional-capabilities)
+- [Keep the Apple character restrained](#keep-the-apple-character-restrained)
+- [Implementation order](#implementation-order)
+- [Home Screen readiness checklist](#home-screen-readiness-checklist)
+- [Primary references](#primary-references)
+
+## Start with the requested mode
+
+- For an audit or review, report evidence and prioritized gaps. Do not edit the target app.
+- For an authorized build or change, implement the smallest complete capability in the target
+ app. Do not stop at a checklist or generic advice.
+- Keep browser behavior as the baseline. Use standalone mode and optional APIs as progressive
+ enhancements.
+- Separate shared-skill work from product implementation into different changesets and reviews.
+
+## Map the live app before editing
+
+Trace the actual runtime path from public URL to rendered shell. Record concrete files and owners
+for:
+
+1. host, middleware, rewrites, redirects, and the live route;
+2. root metadata, nested layouts, viewport, theme color, and icon declarations;
+3. authentication entry, return URL, logout, and session persistence;
+4. top-level navigation, browser history, deep links, and external handoffs;
+5. fixed, sticky, draggable, fullscreen, toast, modal, sheet, and keyboard-adjacent surfaces;
+6. network state, retained drafts, caches, Service Worker registration, and update prompts; and
+7. observability and the existing verification path.
+
+Do not patch a retired or redirect-only route because its name appears canonical. Prefer a few
+route-aware choke points over page-by-page fixes. Establish one explicit owner for each of app
+identity, viewport/theme integration, standalone detection, safe-area tokens, navigation,
+offline/reconnect state, and Service Worker updates.
+
+Preserve the target framework's router, metadata APIs, authentication model, data flow, styling
+system, and existing lifecycle safeguards. Add only the files that framework needs; do not drop a
+generic PWA template into a brownfield app.
+
+## Preserve the browser baseline
+
+Core tasks must work from an ordinary tab without installation or privileged APIs. Standalone
+mode may refine chrome, navigation, safe-area layout, launch behavior, and supported OS
+integrations, but it must not fork the product into two inconsistent applications.
+
+Detect the applied display mode, not a guessed OS version:
+
+```js
+const standalone = window.matchMedia('(display-mode: standalone)').matches;
+```
+
+Use CSS for visual differences where possible:
+
+```css
+@media (display-mode: standalone) {
+ .browser-only-install-help { display: none; }
+}
+```
+
+Feature-detect Service Workers, Notifications, Push, Badging, Wake Lock, orientation locking, and
+other optional APIs at the point of use. A missing capability must leave the main task intact.
+Never make a parsed iOS version the primary branch condition.
+
+## Define identity and launch behavior
+
+Use the framework's native metadata or manifest mechanism to provide the equivalent of:
+
+- a stable `id` that does not change with tracking parameters or incidental routes;
+- `name` and a concise `short_name` that remain recognizable under truncation;
+- a deliberate `start_url` and `scope` aligned with authentication and deep-link behavior;
+- `display: "standalone"` unless the product has a demonstrated reason for another mode;
+- `theme_color` and `background_color` that match the first rendered frame in light and dark
+ contexts; and
+- tested, purpose-appropriate icons with no critical artwork outside the safe zone.
+
+On applicable Safari/iOS versions, an HTML `apple-touch-icon` takes precedence over manifest
+icons. Treat it as an intentional compatibility asset, not a second uncontrolled brand source.
+Legacy Apple web-app meta tags are fallbacks only; prefer the standards-based manifest.
+
+Do not claim that a manifest or Service Worker is universally required for iOS installation.
+iOS/iPadOS 26 can open any Home Screen site as a web app by default, while earlier applicable
+versions use manifest or legacy metadata to request standalone behavior. The manifest still owns
+useful identity and launch configuration.
+
+## Build a complete shell without browser chrome
+
+When the URL bar and browser controls disappear, the product must supply the missing orientation
+and escape routes:
+
+- Keep current location and top-level destinations understandable.
+- Provide visible back, close, cancel, or done actions where browser chrome previously supplied
+ the only exit. Never trap the user.
+- Keep navigation URLs real and deep-linkable. Preserve forward/back history instead of replacing
+ it with visual-only panels.
+- Restore useful context after relaunch when appropriate, but do not bypass authentication or
+ revive sensitive state without consent.
+- Treat out-of-scope links, OAuth, payments, file viewers, and other external transitions as
+ lifecycle boundaries. Preserve the intended return URL and reconcile state on return.
+- Avoid standalone-only navigation that makes the same URL mean something materially different
+ in a browser.
+
+## Own the viewport, safe areas, rotation, and keyboard
+
+Only opt into edge-to-edge layout deliberately. If using `viewport-fit=cover`, define shared
+tokens at the shell and let feature surfaces consume them:
+
+```css
+:root {
+ --safe-top: env(safe-area-inset-top, 0px);
+ --safe-right: env(safe-area-inset-right, 0px);
+ --safe-bottom: env(safe-area-inset-bottom, 0px);
+ --safe-left: env(safe-area-inset-left, 0px);
+}
+
+.app-shell {
+ padding-inline: max(1rem, var(--safe-left)) max(1rem, var(--safe-right));
+}
+```
+
+Use the same tokens for shared headers, tab bars, floating controls, sheets, dialogs, banners,
+toasts, and update prompts. Keep critical controls clear of rounded corners, sensor housings, the
+home indicator, and system edge gestures. Do not fix one page while a shared overlay remains
+unsafe.
+
+Test portrait and landscape rather than assuming inset values. Prefer modern dynamic viewport
+units where they fit the layout. For keyboard-adjacent experiences, observe the actual visible
+viewport when necessary; do not freeze layout to an initial `window.innerHeight`. Keep the focused
+field and its primary action visible, and avoid double-applying keyboard and safe-area offsets.
+
+## Make touch and scrolling feel direct
+
+Apply the core skill's response, gesture, and interruptibility rules, plus these shell constraints:
+
+- Give primary touch targets enough physical area and separation; do not rely on hover.
+- Show pressed feedback immediately and commit on release, preserving cancel-by-dragging-away.
+- Use platform scrolling and overscroll behavior unless a custom interaction has a concrete need.
+- Prevent accidental selection only on controls or drag handles, never across readable content.
+- Keep a visible button alternative for swipe-only actions.
+- Do not claim the system's left or bottom edge for a custom gesture without a compelling need and
+ a tested conflict strategy.
+- Keep input zoom, text selection, copy/paste, password managers, and form autofill working.
+
+## Design lifecycle, offline, and update states
+
+A Home Screen icon raises expectations but does not make the network or process persistent. Define
+visible loading, empty, offline, reconnecting, error, and update-ready states. Distinguish “offline”
+from “server error” and “not authorized.”
+
+If the product needs offline continuity:
+
+- choose an explicit, bounded cache policy rather than caching every response;
+- avoid retaining sensitive records by default;
+- identify which reads work offline and which writes queue, fail, or remain as local drafts;
+- make sync status and conflicts understandable; and
+- preserve unsent work across recoverable failures when practical.
+
+A Service Worker is an enhancement, not proof of offline correctness. Keep its ownership and
+registration singular. Do not install a second updater beside an existing update coordinator.
+When a new worker is ready, preserve dirty-state guards and let the user reload at a safe point;
+never surprise-reload merely because an update exists. Test first load, controlled update, failed
+fetch, reconnect, relaunch, and stale-data behavior separately.
+
+## Earn optional capabilities
+
+Install education, notifications, push, badges, wake lock, and orientation lock are optional. Add
+them only when the product has a real task that benefits.
+
+- Explain the value before presenting install guidance; do not repeatedly nag after dismissal.
+- Request notification permission only from a clear user action and at a moment when the benefit
+ is understandable. Accept refusal without degrading unrelated features.
+- Use notifications for timely utility, not re-engagement noise.
+- Feature-detect `navigator.setAppBadge` and `navigator.clearAppBadge`. On iOS/iPadOS, badge
+ visibility is tied to notification permission even though code may set a count earlier.
+- Request wake or orientation behavior only during the task that needs it; release or recover it
+ when visibility changes.
+
+## Keep the Apple character restrained
+
+Use translucent or Liquid Glass-like treatment as a functional layer for important controls and
+navigation, not as the content background. Keep content on stable, readable surfaces. Adapt
+contrast and material weight to what moves underneath, provide solid fallbacks for reduced
+transparency and increased contrast, and avoid stacked glass.
+
+Do not reduce Apple-like design to blur, oversized corner radii, copied status bars, fake home
+indicators, or native-looking controls that behave unlike their web equivalents. Familiarity,
+clarity, feedback, and respect for user agency matter more than visual mimicry.
+
+Support text scaling with `rem`/`em`-based layout, readable reflow, screen-reader names and state,
+logical focus order, visible focus, external keyboards, reduced motion, reduced transparency,
+increased contrast, and orientation changes. Do not disable zoom to protect a brittle layout.
+
+## Implementation order
+
+For an authorized target-app change:
+
+1. Freeze the live-route map, required contexts, allowed files, and non-goals.
+2. Establish identity and launch metadata through framework-native owners.
+3. Establish shared standalone and safe-area contracts at the shell.
+4. Integrate navigation/history, auth return, storage, network, and update behavior.
+5. Audit every shell consumer and only then fix exceptional leaf surfaces.
+6. Add optional capabilities only after the baseline is complete.
+7. Run deterministic framework checks, then verify the relevant context matrix on real or
+ representative devices. Report contexts not exercised.
+
+## Home Screen readiness checklist
+
+- [ ] Core tasks work in a normal browser without optional APIs.
+- [ ] The manifest identity, launch URL, scope, display mode, colors, and icons are intentional.
+- [ ] Browser and applied standalone modes are detected by capability or media query.
+- [ ] Launch, relaunch, deep links, back/close paths, and external returns preserve orientation.
+- [ ] Authentication redirects return to a coherent, authorized state.
+- [ ] Portrait, landscape, safe areas, system edges, and the home indicator do not cover controls.
+- [ ] The software keyboard keeps focused fields and primary actions reachable.
+- [ ] Shared fixed/sticky controls, overlays, sheets, toasts, and update prompts use one inset
+ contract.
+- [ ] Loading, empty, offline, reconnecting, error, and update-ready states are distinct.
+- [ ] Unsent work and dirty-state guards survive recoverable reconnect/update paths where practical.
+- [ ] Cache and retained-draft policies are bounded, privacy-conscious, and product-specific.
+- [ ] Install, notification, push, and badge prompts follow understandable user intent.
+- [ ] Touch targets, pressed feedback, scroll, selection, zoom, autofill, and system gestures work.
+- [ ] Text scaling, screen readers, focus, external keyboards, reduced motion, reduced
+ transparency, increased contrast, and rotation are covered.
+- [ ] Tested contexts and known gaps are reported explicitly.
+
+## Primary references
+
+- [WebKit: WebKit Features in Safari 26.0](https://webkit.org/blog/17333/webkit-features-in-safari-26-0/)
+- [WebKit: Web Push for Web Apps on iOS and iPadOS](https://webkit.org/blog/13878/web-push-for-web-apps-on-ios-and-ipados/)
+- [WebKit: Badging for Home Screen Web Apps](https://webkit.org/blog/14112/badging-for-home-screen-web-apps/)
+- [WebKit: Designing Websites for iPhone X](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)
+- [W3C: Web Application Manifest](https://www.w3.org/TR/appmanifest/)
+- [Apple Human Interface Guidelines: Layout](https://developer.apple.com/design/human-interface-guidelines/layout)
+- [Apple Human Interface Guidelines: Materials](https://developer.apple.com/design/human-interface-guidelines/materials)