Communitygithub.com

CharbelElBateh/site-personnel

Faites en sorte qu'une application web se sente native sur un téléphone — les petites corrections CSS et meta-tags qui séparent « un site dans un navigateur » de quelque chose qui semble installé.

Qu'est-ce que site-personnel ?

Cette compétence est un guide de correction pour rendre les applications web vraiment natives sur mobile. Elle couvre les problèmes courants comme les états de survol bloqués, les flashs de surbrillance au toucher, le bug du 100vh, le zoom intempestif sur les champs de saisie, les taps lents, le défilement détourné par le pull-to-refresh, le contenu bloqué par l'encoche, la sélection de texte sur les boutons, les carrousels qui défilent dans le mauvais sens et le décalage de couleur de la barre d'état. Chaque correctif est expliqué avec son pourquoi, ses alternatives et les pièges à éviter. La compétence s'appuie sur la philosophie d'Emil Kowalski en matière d'ingénierie de conception et est conçue pour être utilisée lors de la construction ou la révision d'une application web pour mobile, en particulier pour les PWA, les feuilles, les carrousels, les mises en page plein écran et toutes interactions tactiles. Elle ne concerne pas les animations (cela relève de `animate`) ni React Native (c'est `animate-expo`).

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Se sentir natif sur mobile

Réponse initiale

Lorsque cette compétence est invoquée pour la première fois sans question spécifique, répondez uniquement par :

Je suis prêt à rendre votre application web native sur mobile. Ma connaissance vient de la philosophie d'ingénierie de conception d'Emil Kowalski.

Ne fournissez aucune autre information jusqu'à ce que l'utilisateur pose une question.

Une compétence de correction. Elle fait UNE chose : prendre une application web qui ressemble à un site sur un téléphone et supprimer, une par une, les marques qui la trahissent. Elle ne conçoit pas le mouvement (c'est animate), ne révise pas les animations (c'est review-animations) et ne construit pas pour React Native (c'est animate-expo). Les règles ici concernent la couche plateforme — la zone d'affichage, le toucher, le défilement, les zones de sécurité, le chrome du navigateur — là où quelques lignes décident si l'application semble installée ou intégrée.

Posture opérationnelle

Vous êtes un ingénieur de conception senior qui a expédié des tiroirs, des feuilles et des interfaces utilisateur pilotées par le geste sur de vrais téléphones et qui a été brûlé par chaque élément ci-dessous. Vous savez qu'un navigateur de bureau avec la barre d'outils des appareils activée n'est pas un téléphone. Vous savez que la plupart des rapports « l'application est saccadée sur mobile » ne sont pas des problèmes d'animation — ce sont un délai de tap de 300 ms, un flash gris au toucher ou un état de survol qui ne veut pas partir.

Le téléphone de l'utilisateur est la source de vérité. Si vous ne pouvez pas l'exécuter sur le matériel, dites lesquelles des corrections ci-dessous vous pouvez vérifier à partir du code et lesquelles nécessitent un vrai appareil.

Deux modes d'échec, et le premier est le pire :

  1. Corriger ce que le bureau vous montre. Les bogues de cette compétence ne se reproduisent pas dans l'émulation d'appareil de Chrome. Si vous ne testez que là, vous expédiez tous ces bogues.
  2. Recourir à JavaScript quand CSS ou une meta-tag le fait. Presque chaque élément ici est une déclaration. Un hook useIsTouchDevice() pour masquer les états de survol est le mauvais outil ; une requête média est la bonne.

Règles strictes

  1. Chaque correctif est livré avec la raison. Chaque règle ci-dessous a un pourquoi. Appliquez-la là où le pourquoi s'applique, pas globalement par habitude — user-select: none sur le texte du corps est un défaut, sur un bouton c'est correct.
  2. Les requêtes média plutôt que la détection d'appareil. (hover: hover), (pointer: fine), env(), dvh — la plateforme vous dit ce qu'elle peut faire. Ne branchez jamais sur les chaînes d'agent utilisateur ou la largeur d'écran pour deviner le toucher.
  3. Le toucher et la souris ne sont pas exclusifs. iPads avec trackpads, ordinateurs portables avec écrans tactiles, téléphones avec une souris. Écrivez pour les deux à la fois ; filtrez par capacité, pas par appareil.
  4. Ne désactivez jamais le zoom. user-scalable=no et maximum-scale=1 sont des échecs d'accessibilité. Corrigez plutôt la taille de police des entrées, qui est ce qui causait le zoom.
  5. Testez sur le matériel avant de le déclarer terminé. Branchez le téléphone, ouvrez le serveur de développement par IP, utilisez l'inspecteur Web de Safari ou le débogage à distance de Chrome. L'émulation ne peut pas reproduire le survol collant, le délai de tap, le rubber-banding, les zones de sécurité ou le clavier.

La table des symptômes

Commencez ici. Associez ce que l'utilisateur voit, puis lisez la section correspondante pour le pourquoi et le code exact.

ProblèmeSolution
État de survol bloqué après un tapEnvelopper dans @media (hover: hover) and (pointer: fine)
Flash gris/bleu au toucherSupprimer -webkit-tap-highlight-color
Mise en page avec une hauteur incorrecte100dvh (application) ou 100svh (héro)
La page zoome sur l'entréeTaille de police d'entrée 16 px au minimum
Le tap semble lentRetour d'information sur pointer-down + touch-action: manipulation
Pull-to-refresh détourne le défilementoverscroll-behavior: none sur html, body
Le contenu s'arrête à l'encocheviewport-fit=cover + env(safe-area-inset-*)
L'appui long sélectionne le texte du boutonAjouter user-select: none
Le carrousel défile verticalementtouch-action: pan-y sur la surface de geste
La couleur de la barre d'état ne correspond pastheme-color par schéma de couleurs
Correct dans Chrome, incorrect sur le téléphoneTester sur du matériel réel

Les correctifs

1. État de survol bloqué après un tap

Le toucher n'a pas de survol, donc les navigateurs en simulent un : le premier tap sur un élément applique :hover et le laisse là jusqu'à ce que l'utilisateur tape ailleurs. Un bouton qui s'agrandit au survol reste agrandi après avoir été tapé. Filtrez chaque style de survol derrière une requête de capacité.

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

Les deux conditions sont importantes. (hover: hover) signifie que l'entrée principale peut survoler. (pointer: fine) signifie qu'elle est précise, comme une souris — cela exclut les stylets et les appareils Android étranges qui prétendent prendre en charge le survol. Dans Tailwind v4, la variante hover: compile déjà en @media (hover: hover) ; dans v3, définissez future.hoverOnlyWhenSupported.

Les utilisateurs tactiles ont toujours besoin d'un retour de pression. Donnez-leur via :active (voir §5), qui fonctionne sur tous les types d'entrée.

2. Flash gris/bleu au toucher

iOS Safari et Android Chrome peignent une surbrillance translucide sur tout élément tapé qui a un gestionnaire de clic. C'est le signal le plus fort « c'est un site web », et il combat tout retour de pression que vous avez conçu.

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

Définissez-le une fois, globalement. Ensuite, assurez-vous que chaque élément cliquable a son propre état :active, car vous venez de supprimer le seul retour que le navigateur donnait.

3. La mise en page a une hauteur incorrecte

100vh sur mobile est la plus grande zone d'affichage — la hauteur avec le chrome du navigateur réduit. Au chargement de la page, la barre d'URL est visible, donc un élément 100vh dépasse de la hauteur de cette barre, et un bouton épinglé en bas se trouve en dessous. Utilisez les unités dynamiques et petites à la place :

/ * Shell d'application, tiroirs, tout ce qui doit suivre la zone visible lorsque le chrome s'affiche/se masque * /
.app { height: 100dvh; }

/ * Héro et premiers écrans — la plus petite zone d'affichage, donc rien n'est jamais coupé * /
.hero { min-height: 100svh; }

dvh se redimensionne lorsque la barre d'URL se réduit, ce qui est correct pour un shell d'application mais provoque des décalages de mise en page sur le contenu marketing en cours de défilement. svh est stable et ne déborde jamais, ce qui est correct pour un héro. lvh est l'ancien vh — vous ne voulez presque jamais l'utiliser. Gardez une ligne de repli 100vh au-dessus pour les anciens navigateurs uniquement si la matrice de prise en charge du projet l'exige.

4. La page zoome sur l'entrée

iOS Safari zoome la page lorsque le focus atterrit sur une entrée dont la taille de police est inférieure à 16 px, et il ne dézoome pas au blur. L'utilisateur se retrouve avec une mise en page recadrée et décalée. C'est la raison pour laquelle les gens utilisent maximum-scale=1, ce qui est le mauvais correctif (Règle stricte 4).

input, textarea, select {
  font-size: 16px; /* le minimum ; 1rem à la taille racine par défaut */
}

Si le design nécessite un texte plus petit dans les entrées sur le bureau, augmentez-le uniquement là où cela compte :

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

Pendant que vous êtes dans les entrées, définissez le clavier : inputmode="numeric" pour les codes, inputmode="decimal" pour les montants, type="email" et type="tel" pour leurs champs, autocapitalize="none" et autocorrect="off" sur les noms d'utilisateur et les codes, enterkeyhint="send" / "search" / "done" pour que la touche de retour indique ce qu'elle fait.

5. Le tap semble lent

Deux causes distinctes s'empilent ici.

Le délai de clic de 300 ms. Les navigateurs attendent après un tap pour voir si un deuxième tap arrive, car le double-tap zoome. Les navigateurs modernes sautent l'attente lorsque la zone d'affichage est width=device-width, mais pas dans tous les cas (iOS Safari retarde encore sur certains éléments). touch-action: manipulation indique au navigateur que cet élément ne zoome jamais par double-tap, donc il déclenche click immédiatement :

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

Retour d'information au relâchement au lieu de la pression. Les boutons natifs répondent instantanément lorsque votre doigt atterrit. Un bouton web qui ne change que sur click répond lorsque votre doigt quitte, ce qui semble lent même à 0 ms. Stylisez :active, et si vous avez besoin de JavaScript, écoutez pointerdown, pas click :

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

Gardez le retour de pression à 100-160 ms et ease-out. Si la base de code utilise les jetons de la compétence animate, utilisez-les ; ne bifurquez pas vers une nouvelle courbe.

6. Pull-to-refresh détourne le défilement

Le défilement au-delà du haut de la page déclenche pull-to-refresh sur Android Chrome et le rubber band de toute la page sur iOS. Bien sur un document. Mal dans une application avec ses propres conteneurs de défilement, un tiroir que l'utilisateur fait glisser vers le bas, ou un canevas.

html, body {
  overscroll-behavior: none;
}

Ensuite, sur tout élément défilable interne — le contenu d'une feuille, une liste de chat, une barre latérale — empêchez le défilement de s'enchaîner à la page lorsqu'il atteint la fin :

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

contain conserve le rebond du conteneur lui-même (ce qui semble natif) mais empêche la page derrière de bouger. Utilisez none sur la racine, contain sur les enfants. N'utilisez jamais un écouteur touchmove + preventDefault() pour cela — il bloque complètement le défilement et rend l'écouteur non passif, ce qui coûte des images.

7. Le contenu s'arrête à l'encoche

Par défaut, le navigateur letterboxe votre page à l'intérieur de la zone de sécurité, laissant les zones de l'encoche, Dynamic Island et de l'indicateur d'accueil avec la couleur de fond du corps. Une application native peint bord à bord et écarte son contenu de ces zones. Deux étapes :

<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 permet à la page sous l'encoche ; env(safe-area-inset-*) vous donne les encarts pour repousser. Sans la meta-tag, les valeurs env() sont toutes 0px. Les en-têtes fixes, les barres d'onglets en bas, les toasts et les feuilles sont les éléments qui en ont besoin ; le contenu de page normal l'obtient généralement gratuitement via le remplissage de l'en-tête. Donnez à env() une valeur de repli (env(safe-area-inset-bottom, 0px)) lorsque la valeur est utilisée dans un calc.

8. L'appui long sélectionne le texte du bouton

Maintenez un doigt sur un bouton web et iOS sélectionne son étiquette, ou affiche la bulle copier/partager sur un lien. Les contrôles natifs ne font jamais cela. Le texte qui est un contrôle ne doit pas être sélectionnable ; le texte qui est du contenu doit rester sélectionnable.

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;   /* Safari a encore besoin du préfixe */
  -webkit-touch-callout: none; /* pas de bulle d'appui long sur les liens/images utilisés comme contrôles */
}

Ne mettez jamais user-select: none sur body. Les utilisateurs copient des adresses, des messages d'erreur et des numéros de commande ; c'est du contenu.

9. Le carrousel défile verticalement

Un glissement horizontal sur un carrousel est ambigu pour le navigateur — il ne sait pas si vous faites défiler la page ou la piste, donc il devine, et la devinette est souvent la page qui tremble vers le haut pendant que le carrousel bouge. Dites-lui quels axes l'élément possède :

.carousel {
  touch-action: pan-y; /* le carrousel gère l'horizontal ; le navigateur garde le vertical */
}
.drag-surface {
  touch-action: none;  /* un geste personnalisé (une feuille glisser pour rejeter, un curseur) possède tous les axes */
}
.vertical-sheet-handle {
  touch-action: pan-x; /* la feuille gère les glissements verticaux ; l'horizontal reste avec le navigateur */
}

Les valeurs nomment ce que le navigateur peut encore faire. pan-y sur un carrossel horizontal signifie « navigateur, tu gardes le défilement vertical ; je gère l'horizontal ». none signifie que l'élément gère tout — utilisez-le uniquement sur les éléments qui le font vraiment, sinon l'utilisateur ne pourra pas défiler devant eux.

Si le carrousel est un défilement natif plutôt qu'un geste JS, préférez scroll-snap-type: x mandatory sur la piste et scroll-snap-align: start sur les diapositives — la physique du navigateur bat un ressort fait maison, et touch-action devient inutile.

10. La couleur de la barre d'état ne correspond pas

La barre d'état et le chrome du navigateur prennent leur couleur de theme-color. Une seule valeur signifie que le mode clair obtient une barre sombre ou le mode sombre une barre blanche. Donnez à chaque schéma le sien :

<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" />

Faites correspondre la valeur à la couleur tout en haut de votre page — l'arrière-plan de l'en-tête, pas la couleur de la marque. Dans Next.js, définissez-la via l'export viewport (themeColor: [{ media, color }]). Si l'application change de thème avec une classe plutôt que le réglage OS, mettez à jour la balise depuis JavaScript lors du basculement. Pour une PWA installée, apple-mobile-web-app-status-bar-style et le theme_color/background_color du manifeste sont la même décision.

11. Correct dans Chrome, incorrect sur le téléphone

Rien de ce qui précède ne se reproduit dans l'émulation d'appareil. Le survol collant, la surbrillance du tap, l'effet de la barre d'URL sur vh, le zoom des entrées, le délai de clic, le overscroll, les zones de sécurité, le clavier logiciel — chacun est un comportement de matériel réel.

  • Branchez le téléphone en USB, exécutez le serveur de développement sur 0.0.0.0, ouvrez-le par l'IP LAN de la machine.
  • iOS : Safari → Développement → l'appareil. Android : chrome://inspect.
  • Testez sur un téléphone de quelques années, pas le plus récent sur votre bureau. Testez avec le clavier ouvert. Testez en paysage une fois.
  • Testez en tant que PWA installée si c'est une cible ; le mode autonome modifie la zone d'affichage, les zones de sécurité et le comportement de la barre d'état.

Le simulateur Xcode est une amélioration par rapport à l'émulation mais manque toujours la sensation tactile. Le matériel réel est la référence.

Base de référence

Lorsque vous démarrez une application mobile, c'est le strict minimum. Expédiez-le avant le premier composant :

<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%; /* pas d'inflation de police en paysage */
  overscroll-behavior: none;
}

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

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

Et les zones de sécurité là où elles sont nécessaires : header, bottom bar, sheets.

Marquez l'application comme ayant un comportement orienté mobile dès la one-liner de @layer :

@layer base, components, utilities;

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.

Skills associés