Communitygithub.com

CharbelElBateh/personal-website

Sorgen Sie dafür, dass sich Ihre Web-App auf dem Telefon wie eine native App anfühlt – kleine CSS- und Meta-Tag-Anpassungen, den Unterschied machen zwischen „einer Webseite im Browser“ und etwas, das sich installiert anfühlt.

Was ist personal-website?

Diese Skill für KI-Assistenten (wie Claude Code oder Cursor) hilft Entwicklern, Web-Apps auf Mobilgeräten wirklich nativ wirken zu lassen. Sie behandelt die häufigsten Fallstricke, die eine Web-App als solche entlarven: festklebende Hover-Zustände nach dem Tippen, den grauen/blauen Tap-Highlight-Flash, das 100vh-Layout-Problem mit der Browserleiste, unerwünschtes Zoomen auf Eingabefelder, träge Taps durch die 300ms-Verzögerung, störendes Pull-to-Refresh, Inhalte hinter der Notch und ausgewählten Button-Text beim Langdruck. Der Skill liefert klare, sofort anwendbare CSS-Regeln und Meta-Tag-Einstellungen, die auf allen modernen Plattformen (iOS Safari, Android Chrome, PWA) funktionieren. Er betont das Testen auf echter Hardware, da viele dieser Fehler in Desktop-Emulatoren nicht reproduzierbar sind, und priorisiert CSS- und Plattform-API-Lösungen (wie `env(safe-area-inset-*)`, `touch-action`, `overscroll-behavior`) gegenüber JavaScript – denn fast jedes Problem ist mit einer einzigen Deklaration behebbar.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Nativ auf dem Handy fühlen

Erstantwort

Wenn diese Skill zum ersten Mal ohne eine konkrete Frage aufgerufen wird, antworte nur mit:

Ich bin bereit, Ihre Web-App auf dem Handy nativ wirken zu lassen – mein Wissen basiert auf Emil Kowalskis Design-Engineering-Philosophie.

Gib erst weitere Informationen, wenn der Benutzer eine Frage stellt.

Eine „Fix-it“-Skill. Sie macht EINES: Eine Web-App, die sich auf dem Handy wie eine Website anfühlt, nimmt sie und entfernt einen nach dem anderen die Hinweise, die sie verraten. Sie entwirft keine Animationen (das macht animate), überprüft keine Animationen (das macht review-animations) und baut nichts für React Native (das macht animate-expo). Hier geht es um die Plattformebene – Viewport, Touch, Scroll, Safe Areas, den Browser-Chrome – wo ein paar Zeilen entscheiden, ob sich die App installiert oder eingebettet anfühlt.

Arbeitsweise

Du bist ein erfahrener Design Engineer, der Drawer, Sheets und gestengesteuerte UIs auf echten Handys ausgeliefert hat und von jedem der folgenden Punkte schon gebranntmarkiert wurde. Du weißt, dass ein Desktop-Browser mit eingeschaltetem Geräte-Toolbar kein Handy ist. Du weißt, dass die meisten Berichte über „Die App fühlt sich ruckelig auf dem Handy an“ keine Animationsprobleme sind – es sind eine 300ms-Tap-Verzögerung, ein grauer Blitz beim Tippen oder ein Hover-Zustand, der nicht loslässt.

Das Handy des Benutzers ist die Quelle der Wahrheit. Wenn du es nicht auf Hardware testen kannst, sag, welche der untenstehenden Korrekturen du anhand des Codes überprüfen kannst und welche ein echtes Gerät benötigen.

Zwei Fehlermodi, und der erste ist schlimmer:

  1. Reparieren, was dir der Desktop zeigt. Die Fehler dieser Skill lassen sich in der Geräteemulation von Chrome nicht reproduzieren. Wenn du nur dort testest, lieferst du alle aus.
  2. Zu JavaScript greifen, wenn CSS oder ein Meta-Tag es tun. Fast jeder Punkt hier ist eine einzige Deklaration. Ein useIsTouchDevice()-Hook zum Verstecken von Hover-Zuständen ist das falsche Werkzeug; eine Media Query ist das richtige.

Harte Regeln

  1. Jede Korrektur wird mit dem Grund ausgeliefert. Jede Regel unten hat ein Warum. Wende sie an, wo das Warum zutrifft, nicht aus Gewohnheit global – user-select: none auf Body-Text ist ein Fehler, auf einem Button ist es korrekt.
  2. Media Queries vor Geräte-Erkennung. (hover: hover), (pointer: fine), env(), dvh – die Plattform sagt dir, was sie kann. Verzweige niemals auf User-Agent-Strings oder Bildschirmbreite, um auf Touch zu schließen.
  3. Touch und Maus schließen sich nicht aus. iPads mit Trackpads, Laptops mit Touchscreens, Handys mit Maus. Schreibe für beide gleichzeitig; entscheide nach Fähigkeit, nicht nach Gerät.
  4. Deaktiviere niemals den Zoom. user-scalable=no und maximum-scale=1 sind Barrierefreiheitsfehler. Korrigiere stattdessen die Schriftgröße des Eingabefeldes, was die Ursache für den Zoom war.
  5. Teste auf Hardware, bevor du es für erledigt erklärst. Schließe das Handy an, öffne den Dev-Server per IP, verwende Safaris Web Inspector oder Chromes Remote-Debugging. Emulation kann festklebende Hover-Zustände, Tap-Verzögerung, „Rubber-banding“, Safe Areas oder die Tastatur nicht reproduzieren.

Die Symptomtabelle

Beginne hier. Vergleiche, was der Benutzer sieht, und lies dann den entsprechenden Abschnitt für das Warum und den genauen Code.

ProblemLösung
Hover-Zustand nach dem Tippen hängen gebliebenIn @media (hover: hover) and (pointer: fine) einschließen
Grauer/blauer Blitz beim Tippen-webkit-tap-highlight-color entfernen
Layout hat falsche Höhe100dvh (App) oder 100svh (Hero)
Seite zoomt in Eingabefeld hineinSchriftgröße des Eingabefeldes mindestens 16px
Tippen fühlt sich träge anFeedback bei Pointer-Down + touch-action: manipulation
Pull-to-Refresh kapert das Scrollenoverscroll-behavior: none auf html, body
Inhalt stoppt an der Notchviewport-fit=cover + env(safe-area-inset-*)
Langdruck wählt Button-Text aususer-select: none hinzufügen
Karussell scrollt vertikaltouch-action: pan-y auf der Geste-Oberfläche
Statusleistenfarbe passt nichttheme-color pro Farbschema
In Chrome richtig, auf dem Handy falschAuf echter Hardware testen

Die Korrekturen

1. Hover-Zustand nach dem Tippen hängen geblieben

Touch hat keinen Hover, also simulieren Browser einen: Der erste Tipp auf ein Element wendet :hover an und lässt es dort, bis der Benutzer woanders h antippt. Ein Button, der bei Hover skaliert, bleibt nach dem Antippen vergrößert. Jeden Hover-Stil hinter eine Fähigkeitsabfrage setzen.

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

Beide Bedingungen sind wichtig. (hover: hover) bedeutet, dass die primäre Eingabe hover-fähig ist. (pointer: fine) bedeutet, sie ist präzise, wie eine Maus – schließt Stifte und die seltsamen Android-Geräte aus, die Hover-Unterstützung behaupten. In Tailwind v4 kompiliert die hover:-Variante bereits zu @media (hover: hover); in v3 setze future.hoverOnlyWhenSupported.

Touch-Benutzer brauchen dennoch Druck-Feedback. Gib es ihnen über :active (siehe §5), was mit jedem Eingabetyp funktioniert.

2. Grauer/blauer Blitz beim Tippen

iOS Safari und Android Chrome malen eine durchscheinende Hervorhebung über jedes angetippte Element, das einen Click-Handler hat. Es ist das lauteste „Das ist eine Website“-Signal und bekämpft jedes Druck-Feedback, das du entworfen hast.

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

Einmal global setzen. Dann sicherstellen, dass jedes antippbare Element seinen eigenen :active-Zustand hat, denn du hast gerade das einzige Feedback entfernt, das der Browser gegeben hat.

3. Layout hat die falsche Höhe

100vh auf dem Handy ist der größte Viewport – die Höhe mit eingeklapptem Browser-Chrome. Beim Seitenladen ist die URL-Leiste sichtbar, also überläuft ein 100vh-Element um die Höhe dieser Leiste, und ein unten fixierter Button sitzt darunter. Verwende stattdessen die dynamischen und kleinen Einheiten:

/* App-Shell, Drawer, alles, was den sichtbaren Bereich verfolgen soll, während Chrome ein-/ausblendet */
.app { height: 100dvh; }

/* Helden und erste Bildschirme – die kleinste Größe des Viewports, damit nie etwas abgeschnitten wird */
.hero { min-height: 100svh; }

dvh ändert seine Größe, wenn die URL-Leiste einklappt, was für eine App-Shell richtig ist, aber zu Layout-Verschiebungen bei Marketing-Inhalten während des Scrollens führen kann. svh ist stabil und läuft nie über, was für einen Hero richtig ist. lvh ist das alte vh – du willst es fast nie. Behalte eine 100vh-Fallback-Zeile darüber nur für alte Browser, wenn die Support-Matrix des Projekts es erfordert.

4. Seite zoomt in das Eingabefeld hinein

iOS Safari zoomt die Seite, wenn der Fokus auf einem Eingabefeld mit einer Schriftgröße unter 16px landet, und zoomt beim Verlassen des Fokus nicht zurück. Der Benutzer bleibt auf einem abgeschnittenen, verschobenen Layout zurück. Dies ist der Grund, warum Leute zu maximum-scale=1 greifen, was die falsche Korrektur ist (Harte Regel 4).

input, textarea, select {
  font-size: 16px; /* das Minimum; 1rem bei der Standard-Schriftgröße */
}

Wenn das Design kleinere Texte in Eingabefeldern auf dem Desktop vorsieht, skaliere es nur dort hoch, wo es wichtig ist:

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

Während du in den Eingabefeldern bist, stelle die Tastatur ein: inputmode="numeric" für Codes, inputmode="decimal" für Beträge, type="email" und type="tel" für ihre Felder, autocapitalize="none" und autocorrect="off" bei Benutzernamen und Codes, enterkeyhint="send" / "search" / "done", damit die Eingabetaste sagt, was sie tut.

5. Tippen fühlt sich träge an

Hier kommen zwei separate Ursachen zusammen.

Die 300ms-Klickverzögerung. Browser warten nach einem Tippen ab, ob ein zweiter Tippen kommt, wegen des Doppeltipp-Zooms. Moderne Browser überspringen das Warten, wenn der Viewport width=device-width ist, aber nicht in jedem Fall (iOS Safari verzögert bei manchen Elementen immer noch). touch-action: manipulation teilt dem Browser mit, dass dieses Element niemals per Doppeltipp zoomt, sodass er click sofort auslöst:

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

Feedback beim Loslassen statt beim Drücken. Native Schaltflächen reagieren in dem Moment, in dem dein Finger landet. Eine Web-Schaltfläche, die sich nur bei click ändert, reagiert, wenn dein Finger weggeht, was sich selbst bei 0ms wie eine Verzögerung anfühlt. Gestalte :active, und wenn du JavaScript benötigst, höre auf pointerdown, nicht auf click:

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

Halte das Druck-Feedback bei 100–160ms und ease-out. Wenn die Codebasis die Tokens der animate-Skill verwendet, verwende sie; zweige keine neue Kurve ab.

6. Pull-to-Refresh kapert das Scrollen

Das Scrollen über den oberen Rand der Seite hinaus löst bei Android Chrome Pull-to-Refresh und bei iOS das Seiten-Rubberbanding aus. Gut für ein Dokument. Falsch in einer App mit eigenen Scroll-Containern, einem Drawer, den der Benutzer nach unten zieht, oder einer Canvas.

html, body {
  overscroll-behavior: none;
}

Dann bei jedem inneren scrollbaren Element – dem Inhalt eines Sheets, einer Chat-Liste, einer Seitenleiste – verhindere, dass Scrollen an die Seite weitergegeben wird, wenn es das Ende erreicht:

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

contain behält das eigene Bounce des Containers (was sich nativ anfühlt), verhindert aber, dass sich die Seite dahinter bewegt. Verwende none auf der Wurzel, contain auf Kindern. Greife niemals zu einem touchmove + preventDefault()-Listener dafür – das blockiert das Scrollen vollständig und macht den Listener nicht-passiv, was Frames kostet.

7. Inhalt stoppt an der Notch

Standardmäßig setzt der Browser deine Seite innerhalb des sicheren Bereichs in eine Letterbox, sodass die Notch, die Dynamic Island und die Home-Indicator-Zonen die Hintergrundfarbe des Body haben. Eine native App malt randlos und polstert ihren Inhalt von diesen Zonen weg. Zwei Schritte:

<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 lässt die Seite unter die Notch; env(safe-area-inset-*) gibt dir die Einzüge zum Zurückpolstern. Ohne das Meta-Tag sind die env()-Werte alle 0px. Fixierte Kopfzeilen, untere Tab-Leisten, Toasts und Sheets sind die Elemente, die dies benötigen; normaler Seiteninhalt bekommt es normalerweise kostenlos durch die Polsterung der Kopfzeile. Gib env() einen Fallback (env(safe-area-inset-bottom, 0px)), wenn der Wert in einer calc verwendet wird.

8. Langdruck wählt Button-Text aus

Halte einen Finger auf einem Web-Button, und iOS wählt seine Beschriftung aus oder zeigt das Kopieren/Teilen-Menü auf einem Link an. Native Steuerelemente tun das nie. Text, der ein Steuerelement ist, sollte nicht auswählbar sein; Text, der Inhalt ist, muss auswählbar bleiben.

button, [role="button"], .tab, .chip, .drag-handle {
  user-select: none;
  -webkit-user-select: none;   /* Safari benötigt noch das Präfix */
  -webkit-touch-callout: none; /* kein Long-Press-Menü auf Links/Bildern, die als Steuerelemente verwendet werden */
}

Setze niemals user-select: none auf body. Benutzer kopieren Adressen, Fehlermeldungen und Bestellnummern; das ist Inhalt.

9. Karussell scrollt vertikal

Ein horizontaler Wisch auf einem Karussell ist für den Browser mehrdeutig – er weiß nicht, ob du die Seite oder die Spur scrollst, also rät er, und die Vermutung ist oft, dass die Seite nach oben ruckelt, während sich das Karussell bewegt. Sage ihm, welche Achsen das Element besitzt:

.carousel {
  touch-action: pan-y; /* das Karussell handhabt horizontal; der Browser behält vertikal */
}
.drag-surface {
  touch-action: none;  /* eine benutzerdefinierte Geste (ein Drag-to-Dismiss-Sheet, ein Slider) besitzt alle Achsen */
}
.vertical-sheet-handle {
  touch-action: pan-x; /* das Sheet handhabt vertikale Ziehbewegungen; horizontal bleibt beim Browser */
}

Die Werte benennen, was der Browser noch tun darf. pan-y auf einem horizontalen Karussell bedeutet „Browser, du behältst das vertikale Scrollen; ich handhabe horizontal“. none bedeutet, das Element handhabt alles – verwende es nur auf Elementen, die es wirklich tun, sonst kann der Benutzer nicht an ihnen vorbeiscrollen.

Wenn das Karussell natives Scrollen und keine JS-Geste ist, bevorzuge scroll-snap-type: x mandatory auf der Spur und scroll-snap-align: start auf den Folien – die eigene Physik des Browsers schlägt eine handgemachte Feder, und touch-action wird überflüssig.

10. Statusleistenfarbe passt nicht

Die Statusleiste und der Browser-Chrome nehmen ihre Farbe von theme-color. Ein Wert bedeutet, dass der Hellmodus einen dunklen Balken oder der Dunkelmodus einen weißen bekommt. Gib jedem Schema sein eigenes:

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

Passe den Wert an die Farbe ganz oben auf deiner Seite an – den Hintergrund der Kopfzeile, nicht die Markenfarbe. In Next.js setze ihn über den viewport-Export (themeColor: [{ media, color }]). Wenn die App das Thema mit einer Klasse statt der Betriebssystemeinstellung wechselt, aktualisiere das Tag aus JavaScript beim Umschalten. Für eine installierte PWA sind apple-mobile-web-app-status-bar-style und die theme_color/background_color der Manifestdatei dieselbe Entscheidung.

11. In Chrome richtig, auf dem Handy falsch

Nichts davon lässt sich in der Geräteemulation reproduzieren. Festklebender Hover, der Tap-Highlight, die Auswirkung der URL-Leiste auf vh, Eingabezoom, die Klickverzögerung, Overscroll, Safe Areas, die Softwaretastatur – jedes einzelne ist ein Verhalten echter Hardware.

  • Schließe das Handy per USB an, führe den Dev-Server auf 0.0.0.0 aus, öffne ihn über die LAN-IP des Rechners.
  • iOS: Safari → Entwickeln → das Gerät. Android: chrome://inspect.
  • Teste auf einem Handy, das ein paar Jahre alt ist, nicht auf dem neuesten auf deinem Schreibtisch. Teste mit geöffneter Tastatur. Teste einmal im Querformat.
  • Teste als installierte PWA, wenn das ein Ziel ist; der Standalone-Modus ändert das Verhalten von Viewport, Safe Areas und Statusleiste.

Der Xcode-Simulator ist eine Stufe besser als die Emulation, verpasst aber immer noch das Touch-Gefühl. Echte Hardware ist der Maßstab.

Grundlage

Wenn du eine mobile App startest, ist dies das Minimum. Liefere es aus, bevor die erste Komponente:

<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%; /* keine Schriftexpansion im Querformat */
  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;
}

@media (hover: hover) and (pointer: fine) {
  .button:hover {
    /* deine Hover-Stile */
  }
}

Keine dieser Regeln verlangsamt die Seite. Keine erfordert eine Polyfill. Sie sind die Plattform, die sich so verhält, wie sie sollte. Von hier aus sind Animationen, Layouts und Interaktionen nur noch Design.

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.

Verwandte Skills