aictrl-dev/skills

Pulido de IU

Una pantalla puede estar bien organizada y aún sentirse inacabada: dos columnas de campos desalineadas por 17 px, cajas de 88 px en un teléfono de 390 px, una palabra de unidad al final de cada campo, un enlace que no se puede tocar con el pulgar. Las personas lo perciben al instante; los modelos que revisan capturas de pantalla rara vez lo ven. Esta habilidad primero mide, luego juzga, y solo declara un defecto corregido cuando la medida lo confirma.

Entradas

Pregunta solo por lo que falta.

1. Objetivo. Una URL, un archivo HTML, o el componente en un repositorio más una URL donde se renderiza. Necesitas una forma de renderizarlo; si no puedes renderizar nada, indícalo y recurre solo a la rúbrica, marcando cada comprobación medida como "no medida".
2. Alcance (opcional). Un selector CSS para la parte de la página a pulir, por ejemplo el formulario o main. Por defecto: main, si no, body.
3. Referencia (opcional). Una pantalla que el usuario considera mejor (una URL, archivo o captura de pantalla). Mídela también y úsala como dirección para el aspecto; nunca copies su marca, contenido o afirmaciones.

Flujo de trabajo

1. Medir la pantalla actual

Ejecuta el script incluido (necesita Node y Playwright con Chromium; instala con npm i -D playwright && npx playwright install chromium si el proyecto carece de ello):

node <skill-dir>/scripts/measure.cjs <archivo-o-url> --out ui-polish/before [--scope "<selector>"] [--primary "<selector>"] [--hide "<selector>,…"] [--profile form|content]

• Renderiza en teléfono (390×844) y escritorio (1366×900) (código de salida 1 si hay hallazgos de error, 2 en errores de uso, 3 si la ejecución falla), escribe measure.json en --out (resuelto contra el directorio actual) con dos capturas por viewport, <viewport>.png (la primera pantalla) y <viewport>-scope.png (todo el alcance, incluyendo cualquier contenido debajo del pliegue), e imprime cada hallazgo con un selector. Los elementos que comparten una causa son un solo hallazgo con un recuento y selectores de ejemplo, y un hallazgo que es igual en teléfono y escritorio se imprime una vez, con ambos en viewports (usa viewports, no viewport, al filtrar un hallazgo combinado por viewport).
• Los scripts están desactivados por defecto para medir el diseño estático; añade --js para páginas que solo se renderizan con JavaScript. --offline bloquea todas las solicitudes de red excepto la página objetivo (hermético); --assets-only también permite cargar fuentes remotas, hojas de estilo e imágenes, para copias guardadas que necesitan sus fuentes, y contacta con esos hosts.
• --hide establece display: none en superposiciones como un banner de cookies o un lanzador de chat antes de medir y capturar, para que no cubran las capturas ni añadan hallazgos. Un selector --hide que no coincida con nada imprime una advertencia.
• --profile content es para artículos y otras páginas de formato largo: omite las comprobaciones diseñadas para pasos de formulario (escala-tipo, distancia-acción, acción-bajo-pliegue, espacio-muerto). El valor predeterminado es form.
• Varios objetivos en una sola ejecución (measure.cjs <pagina1> <pagina2> … --out dir) van cada uno a dir/<slug>/, y dir/summary.json combina un hallazgo que se repite entre páginas en una línea que lista las páginas; corrige un componente compartido una vez. Compara página por página (--compare before/<slug>/measure.json after/<slug>/measure.json).
• Las comprobaciones y umbrales, y la corrección habitual para cada uno, están en reference/checks.md. Los errores hacen fallar la ejecución; las advertencias necesitan una corrección o una razón declarada.
• Indica una razón una sola vez, no en cada ejecución: un ui-polish.config.json en el directorio actual (o --config <archivo>) lista decisiones aceptadas, por ejemplo { "ignore": [{ "check": "text-size", "selector": ".eyebrow", "reason": "etiquetas de marca secundarias" }] }. Los hallazgos coincidentes pasan a accepted con la razón, se imprimen en su propia sección y no afectan al código de salida. Solo registra una decisión que el propietario haya tomado; nunca añadas una para que los números pasen.

Si se dio una referencia, mídela de la misma manera en ui-polish/reference.

2. Examinarla

Abre las capturas de pantalla (las -scope.png muestran todo el alcance) y recorre los diez puntos de reference/rubric.md. Escribe una tabla de veredicto con una fila por punto (y una fila por subcomprobación del punto 10): aprobado, fallo o n/a, el problema localizado y la corrección. Juzga solo lo que está en la pantalla. Las mediciones son evidencia para la rúbrica, no un reemplazo de ella: una pantalla con cero hallazgos medidos puede fallar en jerarquía, etiquetas y unidades, agrupación o confianza, y esos suelen ser los fallos que la gente nota primero.

3. Planificar las correcciones

Enumera cada hallazgo medido y cada punto fallido de la rúbrica con su corrección, agrupados por el elemento que tocan. Prefiere correcciones estructurales que eliminen varios hallazgos a la vez (por ejemplo, etiquetas sobre campos en una cuadrícula de dos columnas corrige alineación, anchos iguales, relleno de campo, colocación de etiquetas y nombres accesibles juntos) sobre parchear cada hallazgo. Ordena por impacto en la persona que usa la pantalla.

4. Aplicar las correcciones a la fuente

Edita la fuente real: el componente y sus estilos en un repositorio, o el archivo HTML. Reglas:

• Mantén el trabajo y el contenido. Las mismas preguntas, las mismas entradas y unidades, las mismas acciones, la misma marca. No elimines funciones para que una comprobación pase.
• No inventes nada. No añadas hechos que la pantalla no haya declarado en palabras: recuentos de pasos, tiempos, precios, afirmaciones clínicas, legales o de privacidad. Un valor que hayas deducido del código (un aria-valuenow de una barra de progreso, un ancho CSS, un nombre de ruta) tampoco está declarado; enciérralo también entre corchetes. Si el diseño necesita ese texto, usa un marcador de posición entre corchetes (Pregunta [n] de [N], [~3] minutos, [Por qué preguntamos: …]) y listalo para que el propietario lo complete.
• Usa el sistema existente. Reutiliza los tokens, componentes y escala de espaciado del proyecto; añade nuevos valores solo cuando ninguno encaje.
• Manténlo funcionando. Cada control debe seguir haciendo lo que hacía (y, donde estaba roto, funcionar). Mantén visible el foco del teclado.

5. Volver a medir hasta que pase

node <skill-dir>/scripts/measure.cjs <archivo-o-url> --out ui-polish/after [mismas opciones]
node <skill-dir>/scripts/measure.cjs --compare ui-polish/before/measure.json ui-polish/after/measure.json

El paso de comparación también enumera cada pieza de texto nuevo para que el propietario la revise, y falla con numero-inventado cuando el texto nuevo contiene un número fuera de [corchetes] (por ejemplo "Paso 2 de [5]": el 2 nunca fue declarado).

Repite los pasos 4–5 hasta que no haya errores, cada advertencia restante esté corregida o tenga una razón declarada, y cada punto fallido de la rúbrica esté corregido o tenga una razón declarada, como máximo tres rondas. Recorre la rúbrica en las nuevas capturas cada ronda. Cero errores no es suficiente: advertencias como objetivos táctiles de 36 px o etiquetas finales son exactamente los detalles que esta habilidad existe para terminar. Abre las nuevas capturas cada ronda: una comprobación puede pasar mientras la pantalla se ve peor, y eso cuenta como una regresión.

6. Informar

• Capturas de pantalla antes y después en teléfono y escritorio.
• La salida de comparación: corregido, restante (con la razón), nuevo y aceptado (con la razón de la configuración).
• La tabla de veredicto de la rúbrica antes y después, con el motivo de cualquier cosa que aún falle.
• Cada marcador de posición entre corchetes que el propietario necesita completar.
• Cualquier cosa que necesite una decisión de producto en lugar de pulido (derívalo a design-review o al propietario).

Trampas

• Las capturas ocultan la geometría. Un desfase de columna de 17 px o un campo de 88 px en una pantalla de 390 px es obvio para una persona e invisible en una captura reducida. Confía en los números para la geometría y en tus ojos para el equilibrio y la jerarquía.
• Una palabra de unidad al final es la causa habitual de columnas desalineadas. "Pies" y "Pulgadas" tienen diferentes anchos, por lo que todo lo que les sigue se desplaza. Pon etiquetas sobre los campos.
• Las ediciones pequeñas en archivos grandes siguen siendo pequeñas. Cuando la fuente es un archivo grande generado, edita el marcado y los estilos del formulario como un bloque en lugar de parchear atributo por atributo, o el diseño nunca cambiará.
• Detenerse cuando los números pasan es el fallo clásico. La geometría es solo la mitad del pulido; la otra mitad es la rúbrica (un encabezado real, un solo interruptor de modo en lugar de un enlace por campo, una razón para preguntas sensibles, orientación).
• Un token, muchos hallazgos. Un hallazgo de texto pequeño o de objetivo táctil que se repite en cada página generalmente proviene de un token del sistema de diseño o componente. Corrígelo allí, o registra la decisión del propietario en ui-polish.config.json, en lugar de triarlo página por página.
• Pasar las comprobaciones no es el objetivo. Una pantalla enfocada con un encabezado claro, campos agrupados y una acción principal cercana lo es. Usa las comprobaciones para demostrar que llegaste allí.

---

Construido por aictrl.dev. Esta habilidad enseña el flujo de trabajo; aictrl lo operacionaliza — fundamentado en tu backlog, estándares del equipo y grafo de conocimiento del código base. Ver cómo →