thumb-first-platform

拇指优先 · 平台

拇指优先套件的技术验证层。thumb-first-design 用于判断移动端设计应该是什么样（与平台无关的判断），而此技能用于验证实现在真实设备上的表现——标出带文件名:行号和修复建议的客观缺陷，并按严重程度评级。

运行 /thumb-first 可进行设计与平台的综合审查；仅需技术检查时，直接使用此技能。

---

步骤 0 · 检测目标（首先执行）

Web/PWA 与原生应用的相关缺陷截然不同。开始其他操作前，先确定目标平台。

检查代码仓库：

• Web / PWA → next.config.*、vite.config.*、index.html、Web 应用 manifest.json/manifest.webmanifest、Service Worker、Tailwind/CSS。这是此技能的适用范围——继续查看下方的原则和路由说明。
• 原生应用 → package.json 中包含 react-native/expo、app.json/app.config.*（Expo）、ios/+android/ 目录组合、*.xcodeproj/Package.swift/*.swift（SwiftUI/UIKit），或 pubspec.yaml（Flutter）。
• 无法确定或两者兼有（例如带有 Web 目标的 Expo 应用）→ 询问要审查哪个目标。

如果目标是原生应用——不要假装在做 Web 审查。 此技能的检查项（Safari 特性、视口单位、Service Worker、Web 清单）并不适用。应改为：

1. 检查是否安装了可用于移交的原生技能——扫描可用技能 / ~/.claude/skills/，查找有关 React Native、Expo、SwiftUI、原生 iOS/Android 或 Flutter 的技能（例如 react-native-design、building-native-ui、vercel-react-native-skills）。
2. 如果有 → 移交。 明确指出技能名称：“原生技术审查请使用 <skill>——它涵盖原生性能、列表和平台 API。” 并说明 thumb-first-design 仍可用于原生应用的设计判断，因为该层与平台无关。
3. 如果没有 → 如实说明。不要越界：

   thumb-first-platform 涵盖移动端的设计判断（通过 thumb-first-design）和 Web/PWA 技术缺陷。它并未配置原生平台（React Native / SwiftUI / Flutter）的性能或技术审计。对此，请安装专用的原生技能，或使用平台原生工具——Xcode Instruments、Android Studio Profiler、Flipper 或 React Native 性能监视器。

设计层适用于所有目标。此技术层深入覆盖 Web/PWA，并了解原生平台但会将审查移交出去。请诚实说明这条界限。

---

移动端 Web 与 PWA — 核心原则

1. iOS Safari 是最棘手的问题

大多数特性和限制都出现在这里。务必在真实 iOS 设备上测试——模拟器会漏掉关键行为。主要问题：

• PWA 必须通过 Safari 安装（添加到主屏幕）
• 推送通知仅在安装到主屏幕后才可用（iOS 16.4+）
• 未安装的 Web 应用存储上限为 7 天；缓存限制为 50MB；不支持后台同步
• 仅使用 WebKit 渲染（即使 iOS 上的 Chrome 也使用 WebKit）

2. 视口单位很重要

移动端全高布局切勿使用 100vh——浏览器界面会导致溢出。

.hero  { height: 100vh; height: 100svh; }  /* svh for static elements (90% of cases) */
.menu  { height: 100dvh; }                 /* dvh only for elements that should resize */

dvh 会导致布局偏移——谨慎使用。

3. 安全区域内边距不可或缺

刘海屏、灵动岛和 Home 指示条随处可见。

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">

.header     { padding-top: max(1rem, env(safe-area-inset-top)); }
.bottom-nav { padding-bottom: max(1rem, env(safe-area-inset-bottom)); }

4. 触控目标 ≥ 44px

Apple HIG 要求至少 44×44pt；Google 建议使用 48×48dp。点击目标切勿小于此尺寸。

5. 在真实设备上测试

Chrome DevTools 仿真并不可靠——它无法模拟地址栏行为、安全区域内边距、触控延迟细节、iOS Safari CSS 缺陷或真实移动硬件的性能。请使用真实设备，或 BrowserStack/Sauce Labs。

接入与路由

你想做什么？

1. 审查现有移动应用/PWA，排查问题
2. 修复 iOS Safari 专属问题
3. 设置 PWA（manifest、service worker、图标）
4. 优化移动端性能（Core Web Vitals）
5. 调试触控/手势问题
6. 设置推送通知
7. 测试移动端兼容性

等待用户回复，然后阅读对应的工作流并按其执行。

回复	工作流 / 参考资料
1 · “审查”、“检查”、“评估”、“问题”	workflows/audit-mobile-pwa.md
2 · “ios”、“safari”、“iphone”、“apple”	workflows/fix-ios-issues.md
3 · “pwa”、“manifest”、“service worker”、“安装”	workflows/setup-pwa.md
4 · “性能”、“慢”、“vitals”、“lcp”、“cls”	workflows/optimize-performance.md
5 · “触控”、“手势”、“轻触”、“滑动”、“滚动”	阅读 references/touch-interactions.md，然后修复
6 · “推送”、“通知”、“vapid”	阅读 references/push-notifications.md，然后实现
7 · “测试”、“调试”、“模拟”	workflows/test-mobile.md

基于意图的路由（描述了具体问题）：

• “100vh 无效”、“视口”、“高度问题”、“刘海”、“安全区域”、“灵动岛” → references/viewport-layout.md
• “图片太大”、“图片加载慢” → references/image-optimization.md
• “橡皮筋效果”、“弹性滚动” → references/ios-safari-quirks.md

通过 /thumb-first 运行时：总入口只调用审查路径（workflows/audit-mobile-pwa.md），并将发现的问题合并到综合报告中。设置/推送/性能工作流属于构建任务，可直接调用，但不在一站式审查范围内。

---

验证循环 — 每次更改后

1. 构建成功？ pnpm build
2. Lighthouse 审查？ Chrome DevTools → Lighthouse → Mobile + PWA
3. 真实 iOS 设备？ Safari Web Inspector，或 ngrok/localtunnel
4. 是否处理了安全区域？ 纵向和横向，带刘海和不带刘海

按以下格式报告发现：Build: ✓ · Lighthouse PWA: X/100 · iOS Safari: [specific issues]。

---

参考资料索引

均位于 references/：

文件	内容
ios-safari-quirks.md	iOS Safari 错误、CSS 变通方案、限制
android-pwa.md	Android Chrome PWA 行为、WebAPK
viewport-layout.md	100vh 问题、dvh/svh/lvh、安全区域内边距
pwa-manifest.md	manifest.json、图标、启动画面
service-workers.md	缓存策略、离线支持、Next.js 集成
push-notifications.md	Web 推送、VAPID、iOS 与 Android
touch-interactions.md	300ms 延迟、touch-action、手势
performance.md	Core Web Vitals（LCP/INP/CLS）、移动端优化
image-optimization.md	Next.js Image、响应式图片、WebP/AVIF
responsive-patterns.md	常见错误、反模式
testing-debugging.md	Lighthouse、测试工具、iOS 调试

工作流索引

文件	用途
audit-mobile-pwa.md	全面审查移动应用/PWA（/thumb-first 调用的路径）
fix-ios-issues.md	修复 iOS Safari 专属问题
setup-pwa.md	从头配置 PWA
optimize-performance.md	改进 Core Web Vitals
test-mobile.md	测试流程

---

常见问题与快速修复

/* 100vh overflow on mobile */     height: 100svh;            /* or min-height */
/* 300ms tap delay */              button, a { touch-action: manipulation; }
/* rubber-band scroll */           html { overscroll-behavior: none; }

            <meta name="viewport" content="..., viewport-fit=cover">
             <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

**PWA 无法安装：**有效的 manifest.json · HTTPS · 已注册 service worker · 图标包含 192×192 和 512×512。