Communitygithub.com

CharbelElBateh/personal-website

让 Web 应用在手机上感觉像原生应用——一组小巧的 CSS 和 meta 标签修复,将“浏览器中的网站”与“感觉像安装过的应用”区分开来。

personal-website 是什么?

这个技能专注于解决移动端 Web 应用常见的平台层问题,使其在手机上具有原生应用的体验。它覆盖了从触摸交互、视口高度、安全区域到浏览器 UI 行为的数十个具体问题,例如粘性悬停状态、点击高亮闪烁、100vh 高度错误、输入框缩放页面、300ms 点击延迟、下拉刷新劫持滚动、内容被刘海遮挡、长按选中按钮文本、导航轮播滚动方向错误以及状态栏颜色不匹配等。该技能强调使用 CSS 和 meta 标签而非 JavaScript 来修复问题,并严格要求在真实硬件上测试,因为许多问题无法在桌面浏览器模拟器中复现。它不涉及动效设计(由 `animate` 技能处理)或 React Native 开发(由 `animate-expo` 技能处理),而是专注于平台层本身的修复。技能文档以症状表开头,使用户可以快速匹配问题,然后详细解释了每个修复的“为什么”、具体代码和实践原则。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/CharbelElBateh/personal-website/tree/HEAD/.claude/skills/mobile-native

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

在移动设备上营造原生应用的感觉

初始回应

当此技能首次被调用且没有具体问题时,仅回应:

我已准备好让你的 Web 应用在移动设备上感觉像原生应用,我的知识源于 Emil Kowalski 的设计工程理念。

在用户提出问题之前,不提供任何其他信息。

这是一个修复性技能。它只做一件事:获取一个在手机上感觉像网站的应用,然后逐一移除那些暴露其 Web 身份的特征。它不设计动效(那是 animate 的职责),不评审动效(那是 review-animations 的职责),也不为 React Native 构建(那是 animate-expo 的职责)。这里的规则都关乎平台层——视口、触摸、滚动、安全区域、浏览器 chrome——只需几行代码就能决定应用是感觉像安装过的,还是嵌入式的。

操作姿态

你是一位资深的设计工程师,曾将抽屉、底部弹窗和手势驱动的 UI 交付给真实手机,并且被以下每个问题坑过。你知道开启了设备工具栏的桌面浏览器不是手机。你知道大多数“应用在手机上感觉卡顿”的报告都不是动画问题——而是 300ms 的点击延迟、点击时的灰色闪烁,或者无法解除的悬停状态。

用户的手机是真相的来源。如果你无法在硬件上运行,请说明以下哪些修复你可以通过代码验证,哪些需要真实设备。

有两种失败模式,第一种更糟糕:

  1. 修复桌面显示给你的问题。 本技能中的错误在 Chrome 的设备模拟中不会复现。如果你只在那里测试,你会把它们全部发布出去。
  2. 使用 JavaScript 而不是 CSS 或 meta 标签。 这里的每个问题几乎都可以通过一条声明解决。使用 useIsTouchDevice() 钩子来隐藏悬停状态是错误的方式;媒体查询才是正确的。

硬性规则

  1. 每次修复都附带原因。 下面的每个规则都有一个为什么。只在为什么适用的地方应用它,而不是出于习惯全局应用——user-select: none 用在正文文本上是缺陷,用在按钮上则是正确的。
  2. 媒体查询优于设备嗅探。 (hover: hover)、(pointer: fine)、env()、dvh——平台会告诉你它支持什么。永远不要根据用户代理字符串或屏幕宽度来猜测触摸能力。
  3. 触摸和鼠标并不互斥。 带触控板的 iPad、带触摸屏的笔记本电脑、带鼠标的手机。同时为两者编写代码;根据能力而非设备进行判断。
  4. 永远不要禁用缩放。 user-scalable=no 和 maximum-scale=1 是访问性失败。相反,修复导致缩放的输入框字号即可。
  5. 在硬件上测试才能算完成。 连接手机,通过 IP 打开开发服务器,使用 Safari 的 Web Inspector 或 Chrome 远程调试。模拟无法复现粘性悬停、点击延迟、橡皮筋效果、安全区域或键盘。

症状表

从这里开始。匹配用户看到的问题,然后阅读对应章节了解原因和精确代码。

问题解决方案
点击后悬停状态卡住使用 @media (hover: hover) and (pointer: fine) 包裹
点击时出现灰色/蓝色闪烁清除 -webkit-tap-highlight-color
布局高度错误100dvh(应用)或 100svh(首屏)
页面放大输入框输入框字号最小 16px
触摸感觉延迟在触控开始时提供反馈 + touch-action: manipulation
下拉刷新劫持滚动在 html, body 上设置 overscroll-behavior: none
内容在刘海处截断viewport-fit=cover + env(safe-area-inset-*)
长按选中按钮文本添加 user-select: none
轮播图垂直滚动在手势表面上使用 touch-action: pan-y
状态栏颜色不匹配为每个配色方案设置 theme-color
Chrome 上正常,手机上错误在真实硬件上测试

修复方案

1. 点击后悬停状态卡住

触摸没有悬停,因此浏览器会模拟一个:第一次点击元素时应用 :hover 并保持到用户点击别处。一个在悬停时放大的按钮在点击后会保持放大状态。将每个悬停样式都用能力查询包裹起来。

@media (hover: hover) and (pointer: fine) {
  .button:hover {
    background: var(--gray-3);
    transform: scale(1.02);
  }
}

两个条件都很重要。(hover: hover) 表示主要输入设备可以悬停。(pointer: fine) 表示它很精确,比如鼠标——它排除了触控笔和那些声称支持悬停的奇怪 Android 设备。在 Tailwind v4 中,hover: 变量已经编译为 @media (hover: hover);在 v3 中设置 future.hoverOnlyWhenSupported。

触摸用户仍然需要按压反馈。通过 :active(参见 §5)提供,它对所有输入类型都有效。

2. 点击时出现灰色/蓝色闪烁

iOS Safari 和 Android Chrome 在任何具有点击处理器的被点击元素上绘制一个半透明的高亮。这是最明显的“这是一个网站”信号,并且它会与你设计的按压反馈冲突。

html {
  -webkit-tap-highlight-color: transparent;
}

设置一次,全局生效。然后确保每个可点击元素都有自己的 :active 状态,因为你刚刚移除了浏览器提供的唯一反馈。

3. 布局高度错误

移动端 100vh 是最大视口——浏览器 chrome 收缩时的高度。页面加载时 URL 栏可见,因此 100vh 元素会溢出该栏的高度,底部固定的按钮会位于其下。改用动态和小尺寸单位:

/* 应用外壳、抽屉、任何应该跟随可见区域(chrome 显示/隐藏时)的元素 */
.app { height: 100dvh; }

/* 首屏和第一屏——视口最小时的高度,确保不会截断内容 */
.hero { min-height: 100svh; }

dvh 会随着 URL 栏收放而调整大小,这对于应用外壳是正确的,但会导致滚动中的营销内容发生布局偏移。svh 稳定且不会溢出,适合首屏。lvh 是旧的 vh——你几乎不会想用它。只有在项目支持矩阵要求时,才在旧浏览器上方保留一行 100vh 回退。

4. 页面放大输入框

iOS Safari 在焦点落在字号小于 16px 的输入框上时会放大页面,并且在失焦时不会缩回。用户会看到一个裁剪、偏移的布局。这就是人们使用 maximum-scale=1 的原因,但那是错误的修复(硬性规则 4)。

input, textarea, select {
  font-size: 16px; /* 最小值;在默认根字号下为 1rem */
}

如果设计在桌面端输入框中要求更小的文本,只在需要的地方放大:

@media (pointer: coarse) {
  input, textarea, select { font-size: 16px; }
}

在输入框中时,设置键盘:inputmode="numeric" 用于验证码,inputmode="decimal" 用于金额,type="email" 和 type="tel" 用于对应字段,autocapitalize="none" 和 autocorrect="off" 用于用户名和验证码,enterkeyhint="send" / "search" / "done" 使回车键显示其功能。

5. 触摸感觉延迟

这里有两个独立的原因叠加。

300ms 点击延迟。 浏览器在点击后会等待,以判断是否还有第二次点击,因为双击会缩放。现代浏览器在视口为 width=device-width 时会跳过等待,但并非所有情况(iOS Safari 在某些元素上仍然有延迟)。touch-action: manipulation 告诉浏览器这个元素永远不会被双击缩放,因此它会立即触发 click:

button, a, [role="button"], .tappable {
  touch-action: manipulation;
}

在释放时提供反馈而非按下时。 原生按钮在你手指落下的瞬间就会响应。一个只在 click 时变化的 Web 按钮则在你手指离开时才响应,即使延迟为 0ms 也会让人感觉卡顿。为 :active 设置样式,如果需要 JavaScript,监听 pointerdown 而不是 click:

.button {
  transition: transform 100ms var(--ease-out), background 100ms;
}
.button:active {
  transform: scale(0.97);
  background: var(--gray-4);
}

将按压反馈保持在 100–160ms 和 ease-out。如果代码库使用了 animate 技能的设计标记,请使用它们;不要另创一个曲线。

6. 下拉刷新劫持滚动

滚动到页面顶部会触发 Android Chrome 的下拉刷新和 iOS 的整页橡皮筋效果。在文档中没问题。但在具有自己的滚动容器、用户拖动的抽屉或画布的应用中是错误的。

html, body {
  overscroll-behavior: none;
}

然后,在任何内部可滚动元素上——底部弹窗的内容、聊天列表、侧边栏——在滚动到达边界时阻止其传播到页面:

.sheet-content {
  overflow-y: auto;
  overscroll-behavior: contain;
}

contain 保留容器自身的回弹(感觉原生),但阻止其背后的页面移动。在根元素上使用 none,在子元素上使用 contain。永远不要为此使用 touchmove + preventDefault() 监听器——它会完全阻止滚动并使监听器非 passive,从而消耗帧。

7. 内容在刘海处截断

默认情况下,浏览器将你的页面 letterbox 在安全区域内,刘海、灵动岛和 Home 指示器区域显示 body 的背景色。原生应用会边缘到边缘绘制,并将其内容从这些区域中撑开。两步:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
.app-header {
  padding-top: env(safe-area-inset-top);
}
.bottom-bar {
  padding-bottom: env(safe-area-inset-bottom);
}
.sheet {
  padding-bottom: calc(1rem + env(safe-area-inset-bottom));
}

viewport-fit=cover 允许页面进入刘海下方;env(safe-area-inset-*) 提供内边距以将内容撑开。没有这个 meta 标签,env() 的值都是 0px。固定头部、底部标签栏、通知和底部弹窗是需要此处理的元素;普通页面内容通常通过头部的内边距自动获得处理。当在 calc 中使用时,为 env() 提供一个回退值(env(safe-area-inset-bottom, 0px))。

8. 长按选中按钮文本

在 Web 按钮上按住手指,iOS 会选中其标签,或在链接上弹出复制/分享菜单。原生控件永远不会这样做。作为控件的文本不应可选;作为内容的文本必须保持可选。

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;   /* Safari 仍需要前缀 */
  -webkit-touch-callout: none; /* 用于作为控件使用的链接/图像时,禁止长按菜单 */
}

永远不要将 user-select: none 设置在 body 上。用户会复制地址、错误消息和订单号;那是内容。

9. 轮播图垂直滚动

在轮播图上进行水平滑动对浏览器来说是模棱两可的——它不知道你是在滚动页面还是在滚动轨道,因此它会猜测,结果往往是页面在轮播图移动的同时向上抖动。告诉它元素拥有哪些轴:

.carousel {
  touch-action: pan-y; /* 轮播图处理水平方向;浏览器保留垂直方向 */
}
.drag-surface {
  touch-action: none;  /* 自定义手势(拖拽关闭的底部弹窗、滑块)拥有所有轴 */
}
.vertical-sheet-handle {
  touch-action: pan-x; /* 底部弹窗处理垂直拖拽;水平方向留给浏览器 */
}

这些值指定了浏览器仍然可以做什么。pan-y 用于水平轮播图意味着“浏览器,你保留垂直滚动;我来处理水平方向”。none 意味着元素处理一切——只对真正需要的元素使用它,否则用户将无法滚动过它们。

如果轮播图是原生滚动而不是 JS 手势,推荐使用轨道上的 scroll-snap-type: x mandatory 和幻灯片上的 scroll-snap-align: start——浏览器自身的物理效果优于手写的弹簧,且 touch-action 变得不必要。

10. 状态栏颜色不匹配

状态栏和浏览器 chrome 的颜色来源于 theme-color。一个值意味着浅色模式得到深色栏,或深色模式得到白色栏。为每种方案各提供一个:

<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
<meta name="color-scheme" content="light dark" />

将值匹配到页面最顶部的颜色——头部背景,而不是品牌色。在 Next.js 中通过 viewport 导出设置(themeColor: [{ media, color }])。如果应用通过类名而非系统设置切换主题,则在切换时从 JavaScript 更新标签。对于已安装的 PWA,apple-mobile-web-app-status-bar-style 和 manifest 中的 theme_color/background_color 是同样的决策。

11. Chrome 上正常,手机上错误

以上所有问题在设备模拟中均无法复现。粘性悬停、点击高亮、URL 栏对 vh 的影响、输入框缩放、点击延迟、过滚动、安全区域、软件键盘——每一个都是真实硬件的行为。

  • 通过 USB 连接手机,在 0.0.0.0 上运行开发服务器,通过机器的局域网 IP 打开。
  • iOS:Safari → 开发 → 设备。Android:chrome://inspect。
  • 用几年前的手机测试,而不是你桌上最新的那台。在键盘打开时测试。在横屏模式下测试一次。
  • 如果目标是已安装的 PWA,则作为 PWA 进行测试;独立模式会改变视口、安全区域和状态栏行为。

Xcode 模拟器比模拟有所改进,但仍然缺少触摸手感。真实硬件是标准。

基线

在面向移动端的应用开始时,这是最低要求。在第一个组件之前发布它:

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content" />
<meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="#0a0a0a" />
html {
  -webkit-tap-highlight-color: transparent;
  -webkit-text-size-adjust: 100%; /* 横屏时禁止字体放大 */
  overscroll-behavior: none;
}

input, textarea, select {
  font-size: 16px;
}

button, a, [role="button"], .tappable {
  touch-action: manipulation;
}

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;
  -webkit-touch-callout: none;
}

这条基线覆盖了症状表中的 #1、#2、#3、#4、#5、#6 和 #8。然后,根据布局添加 #7(安全区域)、#9(触控操作)和 #10(主题色)。不要在此之上添加通用的重置样式;这是针对平台层的,不是 CSS 重置。

Individual skills in this repo

This repo contains 13 individual skills — each has its own dedicated page.

CharbelElBateh/personal-website

Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use `animate`.

CharbelElBateh/personal-website

Build an animation from scratch, making the decisions in the order that determines whether it feels right — should it animate at all, what purpose, which tool, which properties, which curve and duration, how it interrupts, how it exits. Writes the implementation. Use when asked to animate something, add motion, make a component feel alive, or build a transition. For critiquing existing motion use review-animations; for auditing a whole codebase use improve-animations.

CharbelElBateh/personal-website

Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.

CharbelElBateh/personal-website

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.

CharbelElBateh/personal-website

Guide to Sonner, the React toast library — install and wire up the Toaster, pick the right toast() call, promise and loading toasts, updating, dismissing and persisting toasts, styling, theming and icons, positioning and multiple toasters. Use when working with Sonner or troubleshooting it — toasts that don't appear, appear twice, lose their styles, ignore Tailwind classes, sit behind a modal, or don't follow dark mode.

CharbelElBateh/personal-website

Try to break a piece of UI by feeding it worst-case data — long names, unbreakable emails, one-letter names, missing fields, huge counts, zero items, long labels, non-Latin text, emoji, extreme numbers — then render it behind a "Demo data / Worst case" toggle and report everything that broke, with the fix for each. Use when the user asks to stress-test, break, or find edge cases in a component or screen, or to "try the worst case". For visual design critique use emil-design-eng; for motion use review-animations.

CharbelElBateh/personal-website

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

CharbelElBateh/personal-website

Search a codebase or UI for places that don't animate but should, and reject everything that shouldn't. Read-only; it proposes motion with exact values, it does not implement it. Use when the user asks "what could be animated here?" or wants to "make this feel more alive". For fixing existing animations, use improve-animations or review-animations instead.

CharbelElBateh/personal-website

Survey a codebase's animation and motion code as a senior motion advisor, then produce a prioritized audit and self-contained implementation plans for other agents (or cheaper models) to execute. Read-only on source code — it plans improvements, it does not apply them. Use when the user asks to "improve the animations", "audit the motion", "make this app feel better", or wants a roadmap of animation fixes rather than a review of a single diff.

CharbelElBateh/personal-website

Pick the right library for a given frontend task from a curated, opinionated list — numbers, OTP inputs, charts, command menus, virtualization, drag and drop, toasts, state, styling, and more. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Build multiple genuinely different versions of a UI piece you describe, rendered behind a visual picker so you can flip through them live and promote the one that feels right. Only runs when explicitly invoked; it does not trigger on its own.

CharbelElBateh/personal-website

Reviews animation and motion code against a high craft bar derived from Emil Kowalski's design engineering philosophy. Default to flagging; approval is earned.

CharbelElBateh/personal-website

How to write modern Swift well — modeling with value types, Swift 6 data-race safety and approachable concurrency (@concurrent, main-actor-by-default, actors, task groups), protocols and generics (some vs any), API design, performance and ARC, Swift Testing, macros, and the modern language features agents don't know about yet. Use when writing, reviewing, or migrating Swift, or when a concurrency error, a hang, a data race, a retain cycle, or a performance problem needs fixing.

相关技能