Responsive Web : mobile-first, n'importe quelle stack, vérifié
L'objectif est une mise en page qui fonctionne à chaque largeur, pas à cinq largeurs d'appareils choisies arbitrairement. Les bugs se cachent entre les deux : 412px, 905px, le pixel où max-width: 767px et min-width: 769px ne s'appliquent plus. Cette compétence a donc deux parties qui vont toujours ensemble :
- Construire mobile-first : écrivez la mise en page pour qu'elle s'adapte d'elle-même et nécessite peu de points de rupture.
- Prouver-le : exécutez
scripts/check_responsive.py, qui rend la page et mesure la mise en page à chaque largeur. "Ça a l'air bien" sur une ou deux captures d'écran ne compte pas comme preuve. Terminé signifie que le vérificateur signale 0 erreurs.
Le vérificateur ne voit que la page rendue (boîtes DOM et styles calculés), donc la façon dont le CSS a été écrit ne l'importe pas. C'est ce qui rend cette compétence fonctionnelle pour n'importe quelle technologie.
0. Lire le projet d'abord
Avant d'écrire du CSS, prenez une minute pour trouver :
- Comment les styles sont écrits ici : Tailwind (
tailwind.config.*ou@themeen CSS), variables Bootstrap/SCSS, modules CSS, styled-components/emotion, styles scopés Vue/Svelte, fichiers CSS bruts. Écrivez le nouveau code dans le même système avec les mêmes tokens. Un second système de style est un bug de maintenance. - Les points de rupture existants, et réutilisez-les. N'en inventez pas de nouveaux sauf si le contenu en a besoin.
- Comment voir la page : un fichier
.htmlstatique, ou un serveur de développement (npm run dev,php artisan serve,python manage.py runserver,rails s,dotnet watch...). Vous avez besoin d'une URL ou d'un chemin de fichier pour le vérificateur.
references/stacks.md montre la syntaxe mobile-first et l'emplacement des points de rupture pour les piles courantes.
1. Construire mobile-first
Écrivez les styles de base pour le plus petit écran, sans requête média. Ajoutez de la mise en page à mesure que l'espace grandit, en utilisant des requêtes min-width. Les téléphones obtiennent le CSS le plus simple, le contenu s'empile naturellement, et chaque point de rupture ne fait qu'ajouter des choses. La méthode desktop-first (écrire pour le bureau, puis corriger avec max-width) laisse des trous entre les corrections, et ces trous sont là où la plupart des bugs responsive apparaissent.
Si la base de code est déjà desktop-first, ne la réécrivez pas. Écrivez vos parties nouvelles ou modifiées en mobile-first dans ses conventions, et corrigez ce que le vérificateur trouve.
Privilégiez les mises en page qui s'adaptent sans points de rupture
- Grilles :
grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)). Les colonnes apparaissent quand l'espace le permet, sans point de rupture et sans débordement à 320px (la partiemin(100%, …)est ce qui l'empêche). - Lignes qui doivent passer à la ligne :
display: flex; flex-wrap: wrap; gap: …avec unflex-basisraisonnable. - Tailles :
width: 100%; max-width: 40remau lieu dewidth: 640px. Typographie et espacement fluides avecclamp(min, préféré, max). - Un composant qui apparaît dans des emplacements de différentes largeurs (barre latérale vs colonne principale) : utilisez les requêtes de conteneur (
container-type: inline-size+@container), pour qu'il réponde à son emplacement, pas à la fenêtre. - Ajoutez un point de rupture là où le contenu casse (réduisez la fenêtre jusqu'à ce que quelque chose cloche), pas à une largeur d'appareil.
Casse-mise en page connus. Vérifiez chacun d'eux quand vous l'écrivez.
| Casse | Pourquoi ça casse | Utilisez plutôt |
|---|---|---|
width/min-width fixe en px sur les conteneurs | Plus large qu'un téléphone 320px | max-width + width:100%, %, fr, minmax() |
| Enfant flex/grid avec du contenu long | Les enfants ont par défaut min-width: auto et refusent de rétrécir | min-width: 0 sur l'enfant (ou minmax(0,1fr)) |
| Mots longs, URLs, emails, codes | Aucune opportunité de césure | overflow-wrap: anywhere sur les conteneurs de texte |
white-space: nowrap sur les boutons/étiquettes/nav | Le texte ne peut pas passer à la ligne, pousse la largeur | Autorisez le passage à la ligne, ou des points de suspension avec min-width:0 + un title |
| Images, vidéos, iframes, embeds | Largeur intrinsèque > écran | max-width:100%; height:auto ; aspect-ratio pour les embeds |
| Tableaux | Les colonnes ne peuvent pas rétrécir en dessous du contenu | Enveloppez dans un conteneur overflow-x:auto, ou empilez les lignes sur les petits écrans |
Blocs pre/code | Espaces préservés | overflow-x:auto sur le bloc |
100vw | Inclut la barre de défilement, donc ~15px trop large sur le bureau | 100% (ou 100dvw uniquement pour un vrai plein écran avec précaution) |
height fixe sur les boîtes avec du texte | Le texte passe à plusieurs lignes sur les téléphones et déborde/est rogné | min-height, ou pas de hauteur |
| Positionnement absolu du contenu | Ne prend pas d'espace ; entre en collision à d'autres largeurs | Flux normal/grille ; absolu uniquement pour la décoration |
height: 100vh pour les héros | Les barres du navigateur mobile et les écrans paysage courts le coupent | min-height: 100svh (avec un fallback 100vh avant) |
Ne cachez jamais le symptôme
- Pas de
overflow-x: hiddensurhtml/bodypour empêcher le défilement latéral. Cela cache le bug alors que le contenu est toujours coupé (et cela casseposition: sticky). Trouvez l'élément trop large. Le vérificateur signale ce masquage commeclipped-offscreen. - Pas de
user-scalable=nooumaximum-scale=1. Bloquer le zoom est un échec d'accessibilité (WCAG 1.4.4). - Pas de vérifications JavaScript de la largeur ou de sniffing du user-agent pour la mise en page. Les requêtes média/conteneur CSS le font sans scintillement. JS est acceptable pour le comportement (
matchMedia), pas pour la mise en page. - Ne modifiez pas le test pour le faire passer (augmenter
--min, ajouter des ignorances pour faire disparaître les erreurs).
Tactile, saisie, viewport
<meta name="viewport" content="width=device-width, initial-scale=1">dans chaque en-tête de page.- Cibles tactiles d'au moins 24x24px (WCAG 2.2 AA). Visez 44x44px pour les boutons et les contrôles d'icônes sur les écrans tactiles, et gardez de l'espace entre les voisins.
- Les interfaces utilisateur au survol uniquement (menus, infobulles qui révèlent du contenu) nécessitent
@media (hover: hover)et une alternative au tap. - Les champs de formulaire
font-size: 16pxou plus sur les téléphones, sinon iOS Safari zoome lors de la mise au point. Utilisez les bonstype,inputmodeetautocomplete. - Les téléphones paysage courts (320–430px de haut) sont réels. Les en-têtes collants plus les bannières de cookies ne devraient pas couvrir plus d'un tiers de l'écran. Réduisez-les ou rétractez-les sur les hauteurs courtes (
@media (max-height: 500px)). - Appareils à encoche : utilisez le remplissage
env(safe-area-inset-*)uniquement avecviewport-fit=cover.
Typographie, médias, navigation, contenu
rempour la typographie,clamp()pour les titres, longueur de ligne limitée (max-width: 65chenviron), hauteur de ligne sans unité.- Images :
srcset/sizespour les photos, attributswidth/heightouaspect-ratiopour éviter le changement de mise en page,object-fit: coverlorsque le rapport de la boîte diffère de celui de l'image (sinon elle s'étire). - Navigation : sur les petits écrans, utilisez un vrai
<button>avecaria-expanded/aria-controlsqui ouvre le menu. Affichez les liens en ligne à partir de la largeur où ils tiennent réellement. - Maintenez la parité du contenu : ne supprimez pas de contenu sur mobile parce qu'il était difficile à faire tenir. Réorganisez, condensez ou réduisez-le.
references/patterns.md contient du CSS prêt à copier pour chacun de ces cas (grille, navigation, tableau, formulaire, héros, cartes, médias).
2. Vérifier : exécutez le vérificateur
Configuration unique (Python 3.9+) :
pip install playwright
python -m playwright install chromium
Exécutez-le sur la page rendue. Démarrez d'abord le serveur de développement s'il y en a un.
python <chemin-vers-la-compétence>/scripts/check_responsive.py http://localhost:5173/ --out rapport-responsive
python <chemin-vers-la-compétence>/scripts/check_responsive.py site/index.html --out rapport-responsive # fichier statique
- Plusieurs pages : passez plusieurs URLs. Vérifiez chaque page ou route que vous avez modifiée, plus une qui utilise la mise en page partagée (en-tête/pied de page).
- SPA qui s'affiche tard :
--wait-for "#app main". Pages connectées :--storage-state state.json. - Boucle interne pendant les corrections :
--quick(~5–10 s). Exécutez une exécution complète avant de dire que vous avez terminé (~20–40 s par page). - Code de sortie : 0 = aucune erreur, 1 = erreurs trouvées (ou avertissements avec
--strict), 2 = impossible à exécuter.
Ce qu'il fait : il parcourt 320→1920px par pas de 10px plus les largeurs d'appareils courantes plus les deux côtés de chaque point de rupture trouvé dans le CSS de la page. Il recharge les largeurs clés avec une émulation mobile réelle (tactile, méta viewport) et vérifie quatre téléphones paysage courts. À chaque largeur, il mesure :
| Erreur (à corriger) | Signification |
|---|---|
horizontal-overflow | La page défile latéralement ; nomme l'élément qui dépasse et ce qui le force à être large |
clipped-offscreen | Contenu coupé au bord de l'écran (souvent caché par overflow-x:hidden sur body) |
occluded-target | Un lien/bouton est couvert par un autre élément (ou par une barre fixe à chaque position de défilement) |
small-target | Cible tactile inférieure à 24px et encombrée par des voisins |
text-spill / text-clipped | Le texte sort de sa boîte / est coupé par une taille fixe + overflow:hidden |
text-overlap | Texte de deux blocs non liés dessinés l'un sur l'autre |
distorted-media | Image/vidéo étirée (rapport de boîte ≠ rapport naturel, pas de object-fit) |
viewport-meta, layout-viewport | Méta viewport manquante/bloquant le zoom ; le téléphone s'affiche à la largeur du bureau |
Avertissements (corrigez-les ou expliquez pourquoi pas) : touch-target (contrôles <44px sur les largeurs tactiles), small-text (<12px sur les téléphones), input-zoom (entrées <16px), fixed-coverage (barres fixes/collantes >35 % d'un écran court).
Le rapport (report.md, report.json) regroupe les résultats comme ceci :
1. **horizontal-overflow** à 320-610px ; 568x320 - `body > main.wrap > div.promo` "Fresh coffee..."
- pire : 296 px au-delà du bord droit à 320px
- indices : reste exactement 600px de large à chaque largeur défaillante : une largeur fixe - utilisez max-width/%/fr/minmax à la place
- gros plan : rapport-responsive/closeups/01-horizontal-overflow-320.png
La ligne indices est le diagnostic. Lisez-la avant d'ouvrir le CSS.
3. Boucle de correction
- Corrigez d'abord la plus petite largeur défaillante. Le mobile est la fondation, et le corriger résout souvent le reste.
- Corrigez la cause profonde pointée par les indices, dans la source qu'utilise le projet (la classe Tailwind, la partie SCSS, le composant stylisé), pas avec une surcharge ponctuelle.
references/checks.mdliste les causes et les correctifs pour chaque vérification. - Réexécutez (
--quick), répétez, puis faites une exécution complète. Arrêtez-vous quand il y a 0 erreurs et que chaque avertissement est corrigé ou a une raison. - Quelque chose enfreint intentionnellement une règle (une forme décorative qui déborde de l'écran, un chevauchement délibéré dans un collage héros) ? Marquez cet élément
data-responsive-ignore="text-overlap"(noms des vérifications séparés par des espaces) et ajoutez un commentaire dans le code expliquant pourquoi. Ignorer du contenu réel pour obtenir une exécution verte revient à ne pas tester.
4. Regardez-le
Le vérificateur trouve ce qui est mesurablement cassé. Certains problèmes ne sont pas mesurables : des retours à la ligne maladroits (un mot orphelin sur un bouton), un dernier élément de grille seul, de grandes gouttières vides à 1920px+, un recadrage d'image qui coupe le sujet, un menu techniquement correct mais difficile à utiliser. Ouvrez les captures d'écran enregistrées par l'exécution (screens/320.png, 375, 768, 1024, 1440 et les closeups/) et regardez-les. Si vous ne pouvez pas voir les images, dites-le dans le rapport au lieu de prétendre avoir fait une revue visuelle.
Lorsque vous signalez des problèmes visuels à l'utilisateur, décrivez les éléments par ce qu'ils sont et où ils se trouvent ("le badge de prix sur la photo du produit", "la deuxième carte dans la grille du menu"), pas par leurs noms de classe. Les utilisateurs ne lisent pas les sélecteurs DOM. Gardez les sélecteurs dans vos propres notes pour trouver le code.
5. Demandes d'audit uniquement
Si l'utilisateur demande de vérifier ou d'auditer un site (pas de le corriger), exécutez d'abord le vérificateur complet et rapportez les résultats groupés par sévérité et plage de largeur, avec des captures d'écran, avant de toucher au code. Demandez avant de corriger si le périmètre est important.
6. Dites à l'utilisateur ce qui a été vérifié
Terminez par un résumé court et factuel :
- ce que vous avez modifié (fichiers, composants) ;
- ce qui a été testé : pages,
N largeurs 320–1920px, téléphones paysage ; résultat du vérificateur (0 erreurs, 1 avertissement) ; - chaque avertissement restant et pourquoi il reste ;
- où se trouvent les captures d'écran ;
- ce qui n'a pas été vérifié. Le vérificateur utilise Chromium uniquement, donc les bizarreries de Safari/Firefox, les claviers réels, le zoom 200% uniquement textuel, le RTL, et les pages derrière une connexion sans état de stockage ne sont pas couverts sauf si vous les avez testés séparément.
Fichiers de référence
references/patterns.md: CSS mobile-first prêt à copier pour les blocs de construction courants. Lisez-le lors de la construction d'une nouvelle mise en page ou d'un nouveau composant.references/stacks.md: à quoi ressemblent le mobile-first et les points de rupture dans Tailwind, Bootstrap, SCSS, modules CSS, CSS-in-JS, MUI/Chakra, Vue/Svelte/Angular, templates serveur, plus comment servir chacun pour le vérificateur.references/checks.md: chaque résultat du vérificateur avec les causes typiques, les correctifs et les faux positifs connus. Lisez-le lorsque la cause d'un résultat n'est pas évidente.scripts/selftest/run_selftest.py: prouve que le vérificateur détecte toujours chaque type de bug (14 fixtures). Exécutez-le après avoir modifié le vérificateur.