byceebee/layout-witness

Layout Witness

Haz que la página sea más fácil de escanear y usar. Agrupa claramente los elementos relacionados, mantén la consistencia en componentes repetidos y preserva esas relaciones a medida que cambian el contenido y el tamaño de la ventana. Usa las guías para decidir qué corregir mientras editas.

Usa la extensión de Chrome en la pestaña de desarrollo existente. Conecta su agente local para controlar las guías y leer las mediciones de la página y los elementos como JSON en la terminal. Usa la CLI opcional de Playwright para capturas automatizadas en contextos de navegador nuevos.

Conectar a la pestaña existente

Carga el directorio completo de la habilidad layout-witness como una extensión descomprimida desde chrome://extensions. Usa Chrome 116 o posterior.

1. Establece WITNESS_DIR en el directorio de la habilidad instalada. Ejecuta (cd "$WITNESS_DIR" && npm ci --omit=dev) una vez, luego inicia node "$WITNESS_DIR/scripts/agent.mjs" serve en una terminal persistente.
2. Abre Layout Witness desde la barra de herramientas en la pestaña de desarrollo. En Acceso del agente, pega la URL de emparejamiento que imprimió la terminal y elige Conectar agente. Esto autoriza la pestaña. Si falta el acceso, pide al usuario que empareje esa pestaña una vez.
3. Usa la CLI desde cualquier terminal en la misma máquina. Mantén el servidor local en ejecución durante las ediciones.

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
# Edita el CSS del proyecto y espera a que el servidor de desarrollo lo aplique.
node "$WITNESS_DIR/scripts/agent.mjs" measure

measure imprime las regiones de la página, los resultados de las comprobaciones y el elemento seleccionado actualmente cuando está disponible. Ese elemento puede incluir su cuadro renderizado, margen, borde, relleno, valores de cuadrícula y espacio, tipografía (incluyendo la línea base Y del viewport cuando sea medible) y geometría SVG. Usa un selector que coincida con un elemento visible. Mantén la selección mientras editas y lee su JSON nuevamente después de que el navegador aplique el cambio.

Usa status para verificar la conexión, clear para eliminar solo la guía del elemento, pick para selección manual con clic, import <rules.json> para cargar reglas del proyecto y defaults para restaurar las reglas por defecto. Usa stop para eliminar ambas guías y limpiar la selección para una revisión limpia. Usa start y select para reanudar. Usa disconnect cuando termines si la pestaña debe dejar de aceptar comandos. Las recargas del mismo origen pueden restaurar las guías y una selección en la misma ruta. Un origen diferente o el cierre de la pestaña finaliza el emparejamiento.

Para revisión manual, usa Iniciar guías, Inspeccionar elemento y Detener guías en la ventana emergente de la barra de herramientas. Descargar informe está disponible cuando desees guardar una copia.

Trabajar con las guías activas

1. Establece el diseño esperado. Lee las reglas de diseño y componentes del proyecto, luego verifica los tokens existentes y los componentes hermanos aceptados. Anota las relaciones que importan para la tarea, como un borde de lectura compartido, un espacio entre grupos de navegación o el relleno en línea de un botón. En una página nueva, elige estas relaciones a partir del resumen y registra tus suposiciones. Trata la cuadrícula predeterminada de la extensión como una guía exploratoria.
2. Inspecciona desde la página hasta el elemento. Inicia las guías antes de editar. Captura el punto de partida renderizado y selecciona el elemento que posee el problema. Usa el informe para mediciones exactas cuando las etiquetas estén superpuestas. Para una página nueva, inicia una vez que se renderice el esqueleto y mantén las guías activas mientras agregas secciones y controles.
3. Edita el código fuente con la selección activa. Compara el valor medido con el esperado. Corrige el CSS o el componente compartido que controla la relación. Cuando el servidor de desarrollo aplique la edición, verifica las guías y mediciones del mismo elemento antes de elegir otro. Si una recarga reemplaza el elemento, confirma que la selección restaurada aún se refiere al control previsto. Registra el valor real, el valor esperado y el resultado medido.
4. Revisa el renderizado limpio. Captura primero la guía corregida, luego apaga las guías e inspecciona la página real. Verifica agrupación, jerarquía, alineación, ajuste de línea y enfoque visible en los anchos donde el diseño cambia. Incluye etiquetas largas o contenido traducido y estados relevantes abiertos, colapsados o densos. Reporta los problemas restantes y los anchos y estados que verificaste.

Ámbito	Qué inspeccionar
Esqueleto de la página	Usa las guías de la página para verificar los bordes de lectura compartidos, los márgenes exteriores y cómo se adaptan el encabezado, la barra lateral, el área principal y el pie de página en los puntos de interrupción. En el renderizado limpio, verifica que las acciones recurrentes sigan siendo fáciles de encontrar y que la tarea principal tenga el mayor énfasis visual.
Grupos y componentes repetidos	Usa las pistas de la cuadrícula local para verificar la alineación y los espacios dentro de una región. Compara el espacio entre grupos por separado del relleno y los espacios dentro de cada componente. Mantén los elementos relacionados visualmente agrupados y verifica el orden de lectura cuando los grupos se apilen.
Elementos individuales	Selecciona el control para inspeccionar su cuadro, relleno y espacio entre icono y etiqueta. Compara la altura de línea y la línea base entre etiquetas que deben alinearse. Revisa el tamaño del icono y el trazo dentro de la misma familia, luego juzga el equilibrio óptico al tamaño renderizado. Mide el objetivo interactivo por separado de su glifo.

Para una barra lateral abarrotada, primero verifica si los enlaces relacionados se leen como un grupo y si las secciones adyacentes tienen un espacio claro. Luego selecciona una fila y compara su margen interior y el espacio entre icono y etiqueta con filas equivalentes. Si el componente compartido requiere 16 px en cada lado y la guía muestra 8 px en un lado, restaura el token y vuelve a medir la misma selección. Apaga la guía para verificar la barra lateral expandida y colapsada en contexto.

Usa comprobaciones estrictas para expectativas explícitas como valores de tokens, alineación entre bordes nombrados y desbordamiento. Juzga la jerarquía y el equilibrio óptico en la página renderizada. Usa la escala tipográfica del proyecto para decidir si una línea base debe alinearse.

Referencias de diseño

• Adobe Spectrum 2 explica cómo la proximidad señala relaciones, cómo el espaciado difiere según el ámbito y cómo revisar el espaciado y el trazo de iconos dentro de una familia. Espaciado · Fundamentos de iconos
• Figma muestra cómo elegir guías para la página, regiones anidadas, relleno de componentes y líneas base de texto. Cuadrículas de diseño
• La actualización de diseño de Linear es un caso de estudio sobre acciones de encabezado predecibles y jerarquía visual en un espacio de trabajo denso. Actualización de diseño

Cuando la accesibilidad esté en el ámbito, usa WCAG para verificar el reflujo, las anulaciones de espaciado de texto del usuario y los objetivos de puntero reales, incluidas las excepciones aplicables. Reflujo · Espaciado de texto · Tamaño del objetivo

Capturas automatizadas opcionales

Usa la CLI cuando la automatización necesite contextos de navegador nuevos en distintos anchos de viewport o temas. Requiere Node.js 22+ y Playwright Chromium. Establece WITNESS_DIR en el directorio de la habilidad instalada e instala sus dependencias allí:

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

Ejecuta la CLI desde el proyecto para que sus rutas de configuración y salida se resuelvan allí:

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

Lee la superposición generada y el informe JSON. El modo de captura abre una página nueva para cada ancho y tema. Consulta la referencia de reglas para las definiciones de regiones y comprobaciones. Usa watch para el flujo de trabajo interactivo de la CLI.