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:
- Mobile-First bauen: Schreibe das Layout so, dass es sich selbstständig anpasst und nur wenige Breakpoints benötigt.
- Beweisen: Führe
scripts/check_responsive.pyaus, 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@themein 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 dasmin(100%, …)). - Zeilen, die umbrechen sollen:
display: flex; flex-wrap: wrap; gap: …mit einer sinnvollenflex-basis. - Größen:
width: 100%; max-width: 40remstattwidth: 640px. Fließende Typografie und Abstände mitclamp(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.
| Brecher | Warum es bricht | Verwende stattdessen |
|---|---|---|
Feste width/min-width in px bei Containern | Breiter als ein 320px-Telefon | max-width + width:100%, %, fr, minmax() |
| Flex/Grid-Kind mit langem Inhalt | Kinder haben standardmäßig min-width: auto und weigern sich zu schrumpfen | min-width: 0 am Kind (oder minmax(0,1fr)) |
| Lange Wörter, URLs, E-Mails, Code | Keine Umbruchmöglichkeit | overflow-wrap: anywhere auf Textcontainern |
white-space: nowrap auf Buttons/Labels/Navigation | Text kann nicht umbrechen, drückt die Breite | Umbruch erlauben oder Ellipsis mit min-width:0 + title |
| Bilder, Videos, Iframes, Embeds | Eigenbreite > Bildschirm | max-width:100%; height:auto; aspect-ratio für Embeds |
| Tabellen | Spalten können nicht unter den Inhalt schrumpfen | In overflow-x:auto-Container packen oder Zeilen auf kleinen Bildschirmen stapeln |
pre/code-Blöcke | Beibehaltene Leerzeichen | overflow-x:auto im Block |
100vw | Enthält die Scrollleiste, daher auf dem Desktop ~15px zu breit | 100% (oder 100dvw nur für echten Vollbreiten-Effekt mit Vorsicht) |
Feste height auf Boxen mit Text | Text umbricht auf Telefonen in mehr Zeilen und läuft über oder wird abgeschnitten | min-height oder keine Höhe |
| Absolute Positionierung von Inhalten | Nimmt keinen Platz ein; kollidiert bei anderen Breiten | Normaler Fluss/Grid; absolut nur für Dekoration |
height: 100vh bei Hero-Elementen | Mobile Browser-Leisten und kurze Landscape-Bildschirme schneiden es ab | min-height: 100svh (mit 100vh-Fallback davor) |
Verstecke niemals das Symptom
- Kein
overflow-x: hiddenaufhtml/body, um horizontales Scrollen zu stoppen. Es versteckt den Fehler, während Inhalte immer noch abgeschnitten sind (und es brichtposition: sticky). Finde das Element, das zu breit ist. Der Checker meldet diese Maskierung alsclipped-offscreen. - Kein
user-scalable=noodermaximum-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: 16pxoder mehr auf Telefonen, sonst zoomt iOS Safari beim Fokussieren hinein. Verwende korrektetype,inputmodeundautocomplete. - 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 mitviewport-fit=cover.
Typografie, Medien, Navigation, Inhalt
remfür Schrift,clamp()für Überschriften, Zeilenlänge begrenzt (max-width: 65choder so), zeilenlose line-height.- Bilder:
srcset/sizesfür Fotos,width/height-Attribute oderaspect-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>mitaria-expanded/aria-controlsverwenden, 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-overflow | Seite scrollt seitwärts; nennt das Element, das übersteht, und was es breit macht |
clipped-offscreen | Inhalt am Bildschirmrand abgeschnitten (oft versteckt durch overflow-x:hidden auf dem body) |
occluded-target | Ein Link/Button wird von einem anderen Element verdeckt (oder von einer festen Leiste in jeder Scrollposition) |
small-target | Tippziel unter 24px und von Nachbarn bedrängt |
text-spill / text-clipped | Text läuft aus seiner Box / wird durch feste Größe + overflow:hidden abgeschnitten |
text-overlap | Text zweier unabhängiger Blöcke übereinander gezeichnet |
distorted-media | Bild/Video gestreckt (Box-Verhältnis ≠ natürliches Verhältnis, kein object-fit) |
viewport-meta, layout-viewport | Fehlendes/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
- Behebe zuerst die kleinste fehlerhafte Breite. Mobil ist die Grundlage, und die Behebung behebt oft den Rest.
- 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.mdlistet Ursachen und Behebungen für jede Prüfung auf. - 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. - 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.