Application icon

Application icon 记录的是一个产品在安装、主屏、任务栏、Dock 或浏览器应用窗口里被识别时所使用的图标 contract。它区分产品的原始 mark、给普通上下文使用的 regular any icon、可被平台裁切的 maskable icon、Apple touch icon，以及原生 app bundle 图标；它不把这些角色混成一张“看起来像应用图标”的 PNG。

这个 Topic 关注图标几何、平台合成边界、生成链和缓存更新，而不是品牌本身的重设计，也不是 PWA 的 start_url、offline shell 或 service-worker 生命周期。后者继续由 Progressive web app 负责；只有当任务涉及安装面图标的视觉构图、manifest 用途、平台派生或更新命中率时，才命中本 Topic。

当 Web 或原生产品会在安装后的应用列表、桌面、Dock、主屏或浏览器 standalone window 中显示图标时使用。新增或调整 manifest.icons、apple-touch-icon、favicon、native bundle icon、品牌图标生成脚本，或者用户反馈“安装后图标偏大、被裁切、带了不该有的圆角卡片/阴影、长时间不刷新”时，都应先进入本 Topic。

普通页面内 logo、社交分享图、营销海报、单一 favicon 微调，或只涉及 PWA 的 scope/更新策略而没有图标资产变化时，不应只因为文件名含 icon 就套用。一个项目仅有 manifest 也不足以说明它已建立 application icon contract。

• 保留一个可审查的 canonical mark/source，regular、maskable、Apple 和原生派生物全部由 repo 内生成器导出；不要手工改某张提交过的 PNG 后让源文件、尺寸和哈希失去对应关系。projects/isolappurr-usb-hub.md 的 install asset 版本化与 projects/tuckmark.md 的 browser-static release contract 都说明安装面需要与构建链一起维护。
• regular purpose: "any" 与 purpose: "maskable" 是不同语义资源。W3C 允许同一 icon 声明多个 purpose；本 playbook 选择更严格的交付合同：regular 可以保留透明角和品牌原有构图，maskable 必须使用不透明、full-bleed 的底色，不复用同一字节，也不写成同一资源的 purpose: "any maskable"。这样才能把 W3C/web.dev 所定义的可裁切边界落到可测、可缓存的独立资产上。
• maskable 与 Apple touch 的重要 mark 前景默认放进中心半径 40% 的安全圆；本 playbook 的默认目标是前景 alpha bounding box 最大边为画布的 58%-62%。平台自己决定圆角、squircle、阴影和高光，图源不得预烘焙通用圆角卡片、投影、系统边框或透明 maskable 底色。Apple 的输入应保持未裁切正方形，见 https://developer.apple.com/design/human-interface-guidelines/app-icons/。
• manifest 显式给 regular 写 purpose: "any"，给 maskable 写 purpose: "maskable"；至少维护 192px、512px 和独立 180px Apple touch 输出，并用实际 PNG 尺寸、alpha、MIME、用途和 regular/maskable hash 差异作为回归检查。Chrome 的 safe-area 预览可用于检查，见 https://developer.chrome.com/docs/devtools/progressive-web-apps#view-and-check-maskable-icons。
• 图标字节变化时，安装面 URL 也必须变化。内容派生 query 或 content-addressed filename 都可以，但 manifest、HTML、shortcut、favicon、Apple touch 和 Workbox/precache 引用必须指向同一代资产；只替换稳定 URL 的文件内容会让已安装应用继续显示旧图标。PWA 的路由、缓存与升级时机仍回到 Progressive web app 处理。
• 验收不要只看 alpha bbox。应生成 regular、maskable、Apple touch 在 48px、128px、512px 下的预览，并叠加 circle、squircle 和 macOS rounded-square 裁切；当可见构图变化时，把确定性预览交给主人确认后再冻结 PR 候选。Microsoft 的安装/主题色关系可参考 https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps/how-to/icon-theme-color。

• projects/isolappurr-usb-hub.md：install icon 被当作 PWA runtime contract，生成器、manifest 的 regular/maskable 分离和内容版本 URL 一起维护，适合作为缓存刷新与可安装 surface 的参考。
• projects/tuckmark.md：browser-static release 把 PWA manifest、service worker 和 release bundle 放在同一交付链内，适合检查图标资产不能脱离实际静态发布面。
• skills/style-application-icon/SKILL.md：分发层只把后续维护者引回本 Topic 和 starter workflow，不把这里的几何、平台或缓存规则复制成另一份会漂移的说明。

• 用同一张 regular PNG 同时充当 any 和 maskable。透明角或过大的主体会在平台填底、裁切或放大后失真；应生成独立、不透明、带安全区的 maskable 输出，并测试两者 hash 不同。
• 把浏览器或 macOS 的应用外壳画进源图。预制圆角白卡、阴影、描边或系统高光会与实际平台效果叠加；应只保留产品 mark 和需要的品牌底色，让系统应用自己的外壳。
• 以为换了图像字节就等于用户看到了新图标。安装图标通常被浏览器、service worker 或系统缓存；应让 URL 随内容改变，并验证最终 manifest/HTML/precache 引用的一致性。
• 只在大尺寸裸图上判断“看起来没问题”。48px 与实际 mask 下的可读性、裁切和留白才是安装面的关键；应保留可重复的多尺寸裁切预览和几何测试。
• 把 native platform asset 与 PWA manifest 资产强行共享。它们可以共用 canonical mark，但 Apple/native 平台需要自己的不透明、未预裁切派生物和平台验收；不能用一个带通用系统效果的文件覆盖全部入口。

• projects/isolappurr-usb-hub.md
• projects/tuckmark.md
• isolappurr-usb-hub: web/vite.config.ts
• isolappurr-usb-hub: web/src/pwa/sw.ts
• isolappurr-usb-hub: web/scripts/check-pwa-assets.py
• isolappurr-usb-hub: web/public/manifest.webmanifest
• tuckmark: apps/web/public/manifest.webmanifest
• tuckmark: apps/web/src/pwa-lifecycle.ts
• tuckmark: apps/web/src/pwa/
• skills/style-playbook/references/data/topics/application-icon.json
• skills/style-playbook/references/data/topics/progressive-web-app.json
• skills/style-application-icon/SKILL.md
• https://www.w3.org/TR/appmanifest/#icon-masks
• https://web.dev/articles/maskable-icon
• https://developer.chrome.com/docs/devtools/progressive-web-apps#view-and-check-maskable-icons
• https://developer.apple.com/design/human-interface-guidelines/app-icons/
• https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps/how-to/icon-theme-color