byceebee/layout-witness

Layout Witness

Rendez la page plus facile à parcourir et à utiliser. Regroupez clairement les éléments apparentés, maintenez la cohérence des composants répétés et préservez ces relations lorsque le contenu et la taille de la fenêtre changent. Utilisez les guides pour décider quoi corriger pendant que vous éditez.

Utilisez l'extension Chrome sur l'onglet de développement existant. Associez sa connexion à l'agent local pour contrôler les guides et lire les mesures de la page et des éléments au format JSON dans le terminal. Utilisez l'interface de ligne de commande Playwright optionnelle pour les captures sans surveillance dans des contextes de navigateur frais.

Se connecter à l'onglet existant

Chargez le répertoire complet de la compétence layout-witness comme extension décompressée depuis chrome://extensions. Utilisez Chrome 116 ou une version ultérieure.

1. Définissez WITNESS_DIR sur le répertoire de la compétence installée. Exécutez (cd "$WITNESS_DIR" && npm ci --omit=dev) une fois, puis démarrez node "$WITNESS_DIR/scripts/agent.mjs" serve dans un terminal persistant.
2. Ouvrez Layout Witness depuis la barre d'outils sur l'onglet de développement. Sous Accès agent, collez l'URL d'appariement affichée par le terminal et choisissez Connecter l'agent. Cela autorise le seul onglet. Si l'accès est manquant, demandez à l'utilisateur d'apparier cet onglet une fois.
3. Utilisez l'interface CLI depuis n'importe quel terminal sur la même machine. Gardez le serveur local en cours d'exécution pendant les modifications.

node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# Modifiez le CSS du projet et attendez que le serveur de développement l'applique.
node "$WITNESS_DIR/scripts/agent.mjs" measure

measure affiche les régions de la page, les résultats de vérification et l'élément actuellement sélectionné lorsqu'il est disponible. Cet élément peut inclure sa boîte de rendu, ses marges, bordures, paddings, les valeurs de grille et d'espacement, la typographie (y compris la ligne de base de la fenêtre lorsqu'elle est mesurable) et la géométrie SVG. Utilisez un sélecteur qui correspond à un élément visible. Gardez la sélection pendant l'édition et lisez à nouveau son JSON après que le navigateur a appliqué la modification.

Utilisez status pour vérifier la connexion, clear pour supprimer uniquement le guide de l'élément, pick pour une sélection manuelle par clic, import <rules.json> pour charger les règles du projet et defaults pour restaurer les règles par défaut. Utilisez stop pour supprimer les deux guides et effacer la sélection pour un examen propre. Utilisez start et select pour reprendre. Utilisez disconnect lorsque vous avez terminé si l'onglet doit cesser d'accepter des commandes. Les rechargements de même origine peuvent restaurer les guides et une sélection sur la même route. Une origine différente ou la fermeture de l'onglet met fin à l'appariement.

Pour un examen manuel, utilisez Démarrer les guides, Inspecter l'élément et Arrêter les guides dans la popup de la barre d'outils. Télécharger le rapport est disponible lorsque vous souhaitez enregistrer une copie.

Travailler avec les guides activés

1. Définissez la mise en page attendue. Lisez les règles de mise en page et de composants du projet, puis vérifiez les tokens existants et les composants frères acceptés. Notez les relations qui comptent pour la tâche, comme un bord de lecture partagé, un espace entre les groupes de navigation ou le padding en ligne d'un bouton. Sur une nouvelle page, choisissez ces relations à partir du brief et enregistrez vos hypothèses. Considérez la grille par défaut de l'extension comme un guide exploratoire.
2. Inspectez de la page à l'élément. Activez les guides avant de modifier. Capturez le point de départ rendu et sélectionnez l'élément qui possède le problème. Utilisez le rapport pour des mesures exactes lorsque les étiquettes sont encombrées. Pour une nouvelle page, activez les guides une fois que la coque est rendue et gardez-les actifs pendant que vous ajoutez des sections et des contrôles.
3. Modifiez la source avec la sélection active. Comparez la valeur mesurée à la valeur attendue. Corrigez le CSS ou le composant partagé qui possède la relation. Lorsque le serveur de développement applique la modification, vérifiez les guides et les mesures du même élément avant d'en choisir un autre. Si un rechargement remplace l'élément, confirmez que la sélection restaurée fait toujours référence au contrôle prévu. Enregistrez la valeur réelle, la valeur attendue et le résultat mesuré.
4. Examinez le rendu propre. Capturez d'abord le guide corrigé, puis désactivez les guides et inspectez la page réelle. Vérifiez le regroupement, la hiérarchie, l'alignement, le retour à la ligne et le focus visible aux largeurs où la mise en page change. Incluez les étiquettes longues ou le contenu traduit et les états ouverts, réduits ou denses pertinents. Signalez les problèmes restants ainsi que les largeurs et les états que vous avez vérifiés.

Périmètre	Quoi inspecter
Coque de la page	Utilisez les guides de page pour vérifier les bords de lecture partagés, les gouttières extérieures et la façon dont l'en-tête, la barre latérale, la zone principale et le pied de page s'adaptent aux points de rupture. Dans le rendu propre, vérifiez que les actions récurrentes restent faciles à trouver et que la tâche principale reçoit le plus d'emphase visuelle.
Groupes et composants répétés	Utilisez les pistes de grille locales pour vérifier l'alignement et les extensions au sein d'une région. Comparez l'espace entre les groupes séparément du padding et des espacements au sein de chaque composant. Gardez les éléments apparentés visuellement regroupés et vérifiez l'ordre de lecture lorsque les groupes s'empilent.
Éléments individuels	Sélectionnez le contrôle pour inspecter sa boîte, son padding et l'espace icône-étiquette. Comparez la hauteur de ligne et la ligne de base parmi les étiquettes censées être alignées. Examinez la taille et le trait de l'icône au sein d'une même famille, puis évaluez l'équilibre optique à la taille rendue. Mesurez la cible interactive séparément de son glyphe.

Pour une barre latérale encombrée, vérifiez d'abord si les liens apparentés forment un groupe et si les sections adjacentes ont un espace clair. Sélectionnez ensuite une ligne et comparez son retrait et son espace icône-étiquette avec les lignes équivalentes. Si le composant partagé prévoit 16 px de chaque côté et que le guide indique 8 px d'un côté, rétablissez le token et mesurez à nouveau la même sélection. Désactivez le guide pour vérifier la barre latérale développée et réduite en contexte.

Utilisez des vérifications strictes pour les attentes explicites telles que les valeurs des tokens, l'alignement entre les bords nommés et le débordement. Évaluez la hiérarchie et l'équilibre optique dans la page rendue. Utilisez l'échelle typographique du projet pour décider si une ligne de base doit être alignée.

Références de conception

• Adobe Spectrum 2 explique comment la proximité signale les relations, comment l'espacement diffère selon le périmètre et comment examiner l'espacement et le trait des icônes au sein d'une famille. Espacement · Fondamentaux des icônes
• Figma montre comment choisir des guides pour la page, les régions imbriquées, le padding des composants et les lignes de base du texte. Grilles de mise en page
• La refonte de conception de Linear est une étude de cas sur les actions d'en-tête prévisibles et la hiérarchie visuelle dans un espace de travail dense. Refonte de conception

Lorsque l'accessibilité est dans le périmètre, utilisez WCAG pour vérifier le redimensionnement (reflow), les surcharges d'espacement du texte utilisateur et les cibles de pointage réelles, y compris les exceptions applicables. Redimensionnement · Espacement du texte · Taille de la cible

Captures sans surveillance optionnelles

Utilisez l'interface CLI lorsque l'automatisation nécessite des contextes de navigateur frais sur différentes largeurs de fenêtre ou thèmes. Elle nécessite Node.js 22+ et Playwright Chromium. Définissez WITNESS_DIR sur le répertoire de la compétence installée et installez ses dépendances :

(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)

Exécutez l'interface CLI depuis le projet afin que ses chemins de configuration et de sortie s'y résolvent :

node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
  --config ./layout-witness.json --width 1440 --width 390 --strict \
  --out .layout-witness/review

Lisez la superposition générée et le rapport JSON. Le mode capture ouvre une nouvelle page pour chaque largeur et thème. Consultez la référence des règles pour les définitions de régions et de vérifications. Utilisez watch pour le workflow interactif de l'interface CLI.