CommunityCodierung & Entwicklunggithub.com

Responsive Web: Mobile-First, Jeder Stack, Verifiziert

Erstelle und überprüfe Web-UIs, die bei jeder Bildschirmbreite (320px Telefone bis 2560px Monitore) funktionieren – mit einem Mobile-First-Ansatz, der mit jedem Tech-Stack kompatibel ist. Enthält einen Playwright-Checker, der 150+ Breiten sowie Landscape-Telefone scannt und echte Layoutbrüche misst.

Was ist Responsive Web: Mobile-First, Jeder Stack, Verifiziert?

Dieses Skill befähigt KI-Agenten, responsive Webseiten zu bauen und zu validieren, die bei jeder Bildschirmbreite robust funktionieren. Der Kern ist ein Mobile-First-Ansatz: Basis-Styles werden für das kleinste Display ohne Media Queries geschrieben, und Layouts werden mit `min-width`-Queries nur erweitert. Der mitgelieferte Playwright-Checker (`scripts/check_responsive.py`) scannt über 150 Breiten von 320px bis 1920px in 10px-Schritten, zuzüglich der Breakpoints des Projekts, und erkennt echte Layoutprobleme wie horizontales Scrollen, abgeschnittene Inhalte, überlappende Texte oder zu kleine Touch-Ziele. Da der Checker nur das gerenderte DOM analysiert, funktioniert er mit jedem CSS-Framework (Tailwind, Bootstrap, SCSS, CSS Modules, CSS-in-JS) und jedem JavaScript-Framework (React, Vue, Svelte, Angular) sowie mit serverseitigen Templates. Entwickler erhalten automatische Diagnose und visuelle Berichte mit Screenshots, die ‚Repariere die kleinste fehlerhafte Breite zuerst‘ als Leitstrategie vorgeben. Das Skill unterstützt sowohl Reparatur- als auch reine Audit-Aufträge und stellt sicher, dass jede Änderung faktenbasiert und technisch überprüft ist, bevor sie als abgeschlossen gemeldet wird.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/isikenes35/responsive-web/tree/HEAD

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

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

Dokumentation

Was macht Responsive Web: Mobile-First, Jeder Stack, Verifiziert?

Das Ziel ist ein Layout, das bei jeder Breite funktioniert, nicht nur bei fünf willkürlich gewählten Gerätebreiten. Fehler verstecken sich dazwischen: 412px, 905px, das eine Pixel, bei dem max-width: 767px und min-width: 769px beide nicht greifen. Daher besteht dieses Skill aus zwei Hälften, die immer zusammenkommen:

  1. Mobile-First bauen: Schreibe das Layout so, dass es sich selbstständig anpasst und nur wenige Breakpoints benötigt.
  2. Beweisen: Führe scripts/check_responsive.py aus, das die Seite rendert und das Layout bei jeder Breite misst. „Sieht gut aus für mich“ nach ein oder zwei Screenshots zählt nicht als Beweis. Fertig bedeutet, dass der Checker 0 Fehler meldet.

Der Checker sieht nur die gerenderte Seite (DOM-Boxen und berechnete Styles) – es ist ihm egal, wie das CSS geschrieben wurde. Dadurch funktioniert es mit jeder Technologie.

0. Lies zuerst das Projekt

Bevor du CSS schreibst, nimm dir eine Minute, um Folgendes herauszufinden:

  • Wie Styles hier geschrieben werden: Tailwind (tailwind.config.* oder @theme in CSS), Bootstrap/SCSS-Variablen, CSS-Module, styled-components/emotion, Vue/Svelte Scoped Styles, Plain-CSS-Dateien. Schreibe neuen Code im selben System mit denselben Tokens. Ein zweites Styling-System ist ein Wartungsfehler.
  • Die vorhandenen Breakpoints und verwende sie wieder. Erfinde keine neuen, es sei denn, der Inhalt erfordert einen.
  • Wie die Seite angezeigt wird: eine statische .html-Datei oder ein Dev-Server (npm run dev, php artisan serve, python manage.py runserver, rails s, dotnet watch …). Du brauchst eine URL oder einen Dateipfad für den Checker.

references/stacks.md zeigt die Mobile-First-Syntax und die Breakpoint-Positionen für gängige Stacks.

1. Mobile-First bauen

Schreibe Basis-Styles für den kleinsten Bildschirm ohne Media Query. Füge Layout hinzu, wenn mehr Platz vorhanden ist, und verwende min-width-Queries. Telefone bekommen das einfachste CSS, Inhalte stapeln sich natürlich, und jeder Breakpoint fügt nur Dinge hinzu. Der Desktop-First-Ansatz (Desktop schreiben, dann mit max-width reparieren) hinterlässt Lücken zwischen den Reparaturen, und genau dort entstehen die meisten Responsive-Fehler.

Wenn der Code bereits Desktop-First ist, schreibe ihn nicht um. Schreibe deine neuen oder geänderten Teile Mobile-First innerhalb seiner Konventionen und behebe, was der Checker findet.

Bevorzuge Layouts, die sich ohne Breakpoints anpassen

  • Grids: grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)). Spalten erscheinen, sobald Platz da ist, ohne Breakpoint und ohne Überlauf bei 320px (dafür sorgt das min(100%, …)).
  • Zeilen, die umbrechen sollen: display: flex; flex-wrap: wrap; gap: … mit einer sinnvollen flex-basis.
  • Größen: width: 100%; max-width: 40rem statt width: 640px. Fließende Typografie und Abstände mit clamp(min, bevorzugt, max).
  • Eine Komponente, die in Slots unterschiedlicher Breite erscheint (Sidebar vs. Hauptspalte): Verwende Container Queries (container-type: inline-size + @container), sodass sie auf ihren Slot reagiert, nicht auf das Fenster.
  • Füge einen Breakpoint dort hinzu, wo der Inhalt bricht (verkleinere das Fenster, bis etwas falsch aussieht), nicht bei einer Gerätebreite.

Bekannte Layout-Brecher. Überprüfe jeden, wenn du ihn schreibst.

BrecherWarum es brichtVerwende stattdessen
Feste width/min-width in px bei ContainernBreiter als ein 320px-Telefonmax-width + width:100%, %, fr, minmax()
Flex/Grid-Kind mit langem InhaltKinder haben standardmäßig min-width: auto und weigern sich zu schrumpfenmin-width: 0 am Kind (oder minmax(0,1fr))
Lange Wörter, URLs, E-Mails, CodeKeine Umbruchmöglichkeitoverflow-wrap: anywhere auf Textcontainern
white-space: nowrap auf Buttons/Labels/NavigationText kann nicht umbrechen, drückt die BreiteUmbruch erlauben oder Ellipsis mit min-width:0 + title
Bilder, Videos, Iframes, EmbedsEigenbreite > Bildschirmmax-width:100%; height:auto; aspect-ratio für Embeds
TabellenSpalten können nicht unter den Inhalt schrumpfenIn overflow-x:auto-Container packen oder Zeilen auf kleinen Bildschirmen stapeln
pre/code-BlöckeBeibehaltene Leerzeichenoverflow-x:auto im Block
100vwEnthält die Scrollleiste, daher auf dem Desktop ~15px zu breit100% (oder 100dvw nur für echten Vollbreiten-Effekt mit Vorsicht)
Feste height auf Boxen mit TextText umbricht auf Telefonen in mehr Zeilen und läuft über oder wird abgeschnittenmin-height oder keine Höhe
Absolute Positionierung von InhaltenNimmt keinen Platz ein; kollidiert bei anderen BreitenNormaler Fluss/Grid; absolut nur für Dekoration
height: 100vh bei Hero-ElementenMobile Browser-Leisten und kurze Landscape-Bildschirme schneiden es abmin-height: 100svh (mit 100vh-Fallback davor)

Verstecke niemals das Symptom

  • Kein overflow-x: hidden auf html/body, um horizontales Scrollen zu stoppen. Es versteckt den Fehler, während Inhalte immer noch abgeschnitten sind (und es bricht position: sticky). Finde das Element, das zu breit ist. Der Checker meldet diese Maskierung als clipped-offscreen.
  • Kein user-scalable=no oder maximum-scale=1. Zoom blockieren ist ein Barrierefreiheitsfehler (WCAG 1.4.4).
  • Keine JavaScript-Breitenprüfungen oder User-Agent-Sniffing für Layouts. CSS Media/Container Queries erledigen das ohne Flackern. JS ist für Verhalten in Ordnung (matchMedia), nicht für Layout.
  • Ändere nicht den Test, damit er besteht (Senken von --min, Hinzufügen von Ignorierungen, um Fehler verschwinden zu lassen).

Touch, Eingabe, Viewport

  • <meta name="viewport" content="width=device-width, initial-scale=1"> in jedem Seitenkopf.
  • Tippziele mindestens 24x24px (WCAG 2.2 AA). Ziel: 44x44px für Buttons und Icon-Steuerelemente auf Touch-Bildschirmen, und halte Abstand zwischen benachbarten Elementen.
  • Hover-Only-UI (Menüs, Tooltips, die Inhalte enthüllen) benötigt @media (hover: hover) und eine Tipp-Alternative.
  • Formularfelder font-size: 16px oder mehr auf Telefonen, sonst zoomt iOS Safari beim Fokussieren hinein. Verwende korrekte type, inputmode und autocomplete.
  • Kurze Landscape-Telefone (320–430px hoch) sind real. Sticky-Header plus Cookie-Banner sollten nicht mehr als etwa ein Drittel des Bildschirms bedecken. Klappe sie bei geringer Höhe zusammen oder verkleinere sie (@media (max-height: 500px)).
  • Geräte mit Notch: Verwende env(safe-area-inset-*) Padding nur zusammen mit viewport-fit=cover.

Typografie, Medien, Navigation, Inhalt

  • rem für Schrift, clamp() für Überschriften, Zeilenlänge begrenzt (max-width: 65ch oder so), zeilenlose line-height.
  • Bilder: srcset/sizes für Fotos, width/height-Attribute oder aspect-ratio, um Layout-Shift zu vermeiden, object-fit: cover, wenn sich das Box-Verhältnis vom Bild unterscheidet (sonst wird es gestreckt).
  • Navigation: Auf kleinen Bildschirmen einen echten <button> mit aria-expanded/aria-controls verwenden, der das Menü öffnet. Zeige Inline-Links ab der Breite, bei der sie tatsächlich passen.
  • Inhaltsparität wahren: Lasse Inhalte auf Mobilgeräten nicht weg, nur weil sie schwer unterzubringen waren. Ordne neu, fasse zusammen oder klappe sie ein.

references/patterns.md enthält kopierfertiges CSS für jeden dieser Punkte (Grid, Nav, Tabelle, Formular, Hero, Karten, Medien).

2. Überprüfen: Führe den Checker aus

Einmalige Einrichtung (Python 3.9+):

pip install playwright
python -m playwright install chromium

Führe ihn gegen die gerenderte Seite aus. Starte zuerst den Dev-Server, falls vorhanden.

python <skill-dir>/scripts/check_responsive.py http://localhost:5173/ --out responsive-report
python <skill-dir>/scripts/check_responsive.py site/index.html --out responsive-report   # statische Datei
  • Mehrere Seiten: Übergib mehrere URLs. Überprüfe jede Seite oder Route, die du geändert hast, plus eine, die das gemeinsame Layout (Header/Footer) verwendet.
  • SPA, die spät rendert: --wait-for "#app main". Eingeloggte Seiten: --storage-state state.json.
  • Innere Schleife während der Fehlerbehebung: --quick (~5–10 s). Führe einen vollständigen Lauf aus, bevor du sagst, dass du fertig bist (~20–40 s pro Seite).
  • Exit-Code: 0 = keine Fehler, 1 = Fehler gefunden (oder Warnungen mit --strict), 2 = konnte nicht ausgeführt werden.

Was es tut: Es scannt 320→1920px in 10px-Schritten plus gängige Gerätebreiten plus beide Seiten jedes Breakpoints, der im CSS der Seite gefunden wird. Es lädt wichtige Breiten mit echter Mobile-Emulation (Touch, Meta-Viewport) neu und überprüft vier kurze Landscape-Telefone. Bei jeder Breite misst es:

Fehler (muss behoben werden)Bedeutung
horizontal-overflowSeite scrollt seitwärts; nennt das Element, das übersteht, und was es breit macht
clipped-offscreenInhalt am Bildschirmrand abgeschnitten (oft versteckt durch overflow-x:hidden auf dem body)
occluded-targetEin Link/Button wird von einem anderen Element verdeckt (oder von einer festen Leiste in jeder Scrollposition)
small-targetTippziel unter 24px und von Nachbarn bedrängt
text-spill / text-clippedText läuft aus seiner Box / wird durch feste Größe + overflow:hidden abgeschnitten
text-overlapText zweier unabhängiger Blöcke übereinander gezeichnet
distorted-mediaBild/Video gestreckt (Box-Verhältnis ≠ natürliches Verhältnis, kein object-fit)
viewport-meta, layout-viewportFehlendes/Zoom-blockierendes Viewport-Meta; Telefon rendert mit Desktop-Breite

Warnungen (beheben oder erklären, warum nicht): touch-target (<44px Steuerelemente auf Touch-Breiten), small-text (<12px auf Telefonen), input-zoom (<16px Eingabefelder), fixed-coverage (fixed/sticky-Leisten >35% eines kurzen Bildschirms).

Der Bericht (report.md, report.json) gruppiert die Funde wie folgt:

1. **horizontal-overflow** bei 320-610px; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
   - worst: 296 px past right edge at 320px
   - clues: stays exactly 600px wide at every failing width: a fixed width - use max-width/%/fr/minmax instead
   - close-up: responsive-report/closeups/01-horizontal-overflow-320.png

Die clues-Zeile ist die Diagnose. Lies sie, bevor du das CSS öffnest.

3. Fehlerbehebungsschleife

  1. Behebe zuerst die kleinste fehlerhafte Breite. Mobil ist die Grundlage, und die Behebung behebt oft den Rest.
  2. Behebe die Ursache, auf die die Hinweise zeigen, in der vom Projekt verwendeten Quelle (die Tailwind-Klasse, das SCSS-Partial, die styled component), nicht mit einem einmaligen Überschreiben. references/checks.md listet Ursachen und Behebungen für jede Prüfung auf.
  3. Führe erneut aus (--quick), wiederhole, dann mache einen vollständigen Lauf. Höre auf, wenn es 0 Fehler gibt und jede Warnung behoben ist oder einen Grund hat.
  4. Etwas bricht absichtlich eine Regel (ein dekoratives Element, das vom Bildschirm läuft, eine bewusste Überlappung in einer Hero-Collage)? Markiere dieses Element mit data-responsive-ignore="text-overlap" (durch Leerzeichen getrennte Prüfnamen) und füge einen Kommentar im Code hinzu, der erklärt, warum. Echte Inhalte zu ignorieren, um einen grünen Lauf zu erhalten, ist dasselbe wie nicht zu testen.

4. Schau es dir an

Der Checker findet, was messbar kaputt ist. Manche Probleme sind nicht messbar: ungeschickte Umbrüche (ein einzelnes Wort auf einem Button), ein einsames letztes Grid-Element, riesige leere Ränder bei 1920px+, ein Bildausschnitt, der das Motiv abschneidet, ein Menü, das technisch in Ordnung, aber schwer zu bedienen ist. Öffne die Screenshots, die der Lauf gespeichert hat (screens/320.png, 375, 768, 1024, 1440 und die closeups/) und schau sie dir an. Wenn du keine Bilder ansehen kannst, sag das im Bericht, anstatt eine visuelle Überprüfung zu behaupten.

Wenn du dem Benutzer visuelle Probleme meldest, beschreibe Elemente nach ihrem Was und Wo („das Preisabzeichen auf dem Produktfoto“, „die zweite Karte im Menü-Grid“), nicht nach Klassennamen. Benutzer lesen keine DOM-Selektoren. Behalte die Selektoren in deinen eigenen Notizen, um den Code zu finden.

5. Nur-Audit-Anfragen

Wenn der Benutzer bittet, eine Seite zu überprüfen oder zu auditieren (nicht zu reparieren), führe zuerst den vollständigen Checker aus und melde die Ergebnisse gruppiert nach Schweregrad und Breitenbereich, mit Screenshots, bevor du den Code anfasst. Frage vor der Reparatur, ob der Umfang groß ist.

6. Teile dem Benutzer mit, was überprüft wurde

Beende mit einer kurzen, sachlichen Zusammenfassung:

  • was du geändert hast (Dateien, Komponenten);
  • was getestet wurde: Seiten, N Breiten 320–1920px, Landscape-Telefone; Checker-Ergebnis (0 Fehler, 1 Warnung);
  • jede verbleibende Warnung und warum sie bleibt;
  • wo die Screenshots sind;
  • was nicht überprüft wurde. Der Checker verwendet nur Chromium, daher werden Safari/Firefox-Besonderheiten, echte Tastaturen, reine Text-200%-Zoom, RTL und Seiten hinter Login ohne Storage-State nicht abgedeckt, es sei denn, du hast sie separat getestet.

Referenzdateien

  • references/patterns.md: Kopierfertiges Mobile-First-CSS für gängige Bausteine. Lies es, wenn du ein neues Layout oder eine neue Komponente erstellst.
  • references/stacks.md: Wie Mobile-First und Breakpoints in Tailwind, Bootstrap, SCSS, CSS-Modulen, CSS-in-JS, MUI/Chakra, Vue/Svelte/Angular, Server-Templates aussehen, plus wie man jede für den Checker bereitstellt.
  • references/checks.md: Jeder Checker-Fund mit typischen Ursachen, Behebungen und bekannten Fehlalarmen. Lies es, wenn die Ursache eines Fundes nicht offensichtlich ist.
  • scripts/selftest/run_selftest.py: Beweist, dass der Checker immer noch jeden Fehlertyp (14 Fixtures) erkennt. Führe es nach der Bearbeitung des Checkers aus.

Verwandte Skills