ckmirafss/easy-on-the-eyes

Fácil para los Ojos

La mayor parte de la fatiga visual frente a una pantalla proviene de cosas que un sitio web no puede tocar: parpadeo, distancia de enfoque, visión no corregida, la habitación. Lo que un sitio controla es cuánto trabajo visual extra exige. Esta skill elimina ese trabajo extra y dice qué tan sólida es la evidencia para cada regla.

También evita que una página cómoda parezca una plantilla. Estudia sitios reales en funcionamiento antes de diseñar y contiene un conjunto de reglas de artesanía para las elecciones que hacen que el trabajo parezca generado.

La afirmación que puedes hacer

Di que el diseño "no agrega esfuerzo visual evitable". Nunca escribas que un diseño previene, reduce o cura la fatiga visual, protege los ojos, o es "seguro para luz azul". No describas el modo oscuro, los tintes cálidos o las fuentes especiales como características de salud. Si el usuario solicita ese tipo de texto, explica por qué y ofrece la redacción honesta.

Modos

Lee los argumentos con los que se invocó la skill.

• Sin argumento, o una tarea de compilación. Para una página o sección nueva, primero estudia referencias (ver "Estudiar antes de diseñar"). Luego aplica las reglas mientras escribes o editas la UI. Comienza desde assets/tokens.css cuando el proyecto aún no tenga tokens de color o tipo. Cuando la UI esté escrita, ejecuta audit.mjs en el código fuente e inspect.mjs en la página renderizada, y revisa "Lo que el script no puede ver" antes de dar por terminado.
• audit (opcionalmente seguido de una ruta). Ejecuta el script, luego revisa lo que un script no puede ver. Informa con la plantilla a continuación. No cambies nada.
• study seguido de una o más URLs. Inspecciona cada página e informa su resumen de diseño: qué hace, qué vale la pena tomar prestado y qué reglas de comodidad infringe. No cambies nada.
• fix (opcionalmente seguido de una ruta). Ejecuta la auditoría. Corrige errores, luego advertencias. Deja una nota en paz a menos que corregir un error o advertencia dependa de ella, o tu propia revisión muestre que es un problema real. Vuelve a ejecutar el script e informa.

Ejecutar el script

Ejecútalo desde la raíz del proyecto y dale la ruta a verificar. El script vive en la carpeta scripts/ de esta skill, así que usa la ruta desde la que se cargó esta skill:

node <skill-dir>/scripts/audit.mjs src                 # informe en texto, sale con 1 si hay error
node <skill-dir>/scripts/audit.mjs src --json          # legible por máquina
node <skill-dir>/scripts/audit.mjs src --strict        # sale con 1 también en advertencias
node <skill-dir>/scripts/audit.mjs contrast "#1f2328" "#ffffff"          # un par
node <skill-dir>/scripts/audit.mjs contrast "#8a8f98" "#ffffff" --min 3  # un borde o icono

node <skill-dir>/scripts/inspect.mjs https://example.com              # resumen de diseño y verificación de comodidad renderizada
node <skill-dir>/scripts/inspect.mjs http://localhost:3000 --out fotos # también guarda capturas de pantalla en claro y oscuro
node <skill-dir>/scripts/inspect.mjs dist/index.html --json

• audit.mjs lee archivos fuente. inspect.mjs abre una página en un navegador real, por lo que mide lo que el lector obtiene: el contraste del texto real sobre su fondo real, caracteres reales por línea, si existe un esquema oscuro y si el movimiento se detiene cuando se solicita movimiento reducido.
• inspect.mjs funciona en cualquier URL o archivo HTML local. Necesita Playwright en el proyecto (npm i -D playwright && npx playwright install chromium). Si falta y no puedes instalarlo, di que la verificación renderizada no se ejecutó.
• Se requiere una ruta. Si el usuario no dio ninguna, usa la carpeta que contiene el código fuente de la UI.
• Los colores pueden ser hexadecimales, rgb(), hsl(), oklch(), white o black.
• Para silenciar un hallazgo que es intencional, pon un comentario que contenga easy-on-the-eyes-ignore en esa línea, o easy-on-the-eyes-ignore-next-line en la línea anterior.
• El script necesita Node 18 o posterior y no tiene dependencias. Si Node falta, aplica las reglas manualmente y di que el script no se ejecutó.

Ambos scripts informan bajo los IDs de regla en la tabla a continuación. Usa esos mismos IDs en tu informe.

Estudiar antes de diseñar

Los modelos producen el promedio de lo que han visto, y el promedio es lo que la gente reconoce como generado. Mirar primero trabajos específicos y en funcionamiento te da decisiones reales a las que reaccionar.

1. Elige de tres a cinco sitios en vivo en la misma categoría de lo que estás construyendo. Usa los que nombre el usuario. De lo contrario, encuéntralos con búsqueda web, o con cualquier herramienta de referencia de diseño o captura de pantalla conectada a la sesión.
2. Ejecuta inspect.mjs en cada uno, con --out para que puedas abrir las capturas de pantalla y mirarlas.
3. Para cada uno, anota las fuentes y la escala tipográfica, cuántos colores usa y dónde va el acento, la longitud de línea, la estructura de secciones y la única cosa que lo hace reconocible.
4. Lee los hallazgos de comodidad para cada referencia. Los sitios admirados a menudo envían texto pequeño, contraste débil y mucho movimiento. Toma prestada la composición y deja eso atrás. references/craft.md tiene la tabla.
5. Dile al usuario qué sitios estudiaste y qué tomaste de cada uno. Toma prestada estructura y decisiones. Nunca copies el nombre, logotipo, redacción, imágenes o diseño exacto de una marca.

Si no puedes abrir ninguna referencia, dilo y diseña a partir de las reglas y references/craft.md.

Grados de evidencia

Cada regla lleva un grado. Repite el grado cuando expliques un hallazgo, para que nadie confunda un hábito con un hecho.

Grado	Significado
research	Respaldado por estudios controlados o revisiones sistemáticas
standard	Establecido por un criterio de éxito de WCAG 2.2. El archivo de referencia da el criterio y su nivel
convention	Sensato y ampliamente implementado, pero sin ensayos detrás
inference	Derivado de investigaciones sobre un estímulo relacionado, no probado en páginas web

Reglas

La gravedad decide el orden: primero errores, luego advertencias, luego notas. Dentro de una gravedad, trabaja hacia abajo en la tabla. La gravedad mostrada es la habitual. El script la reduce cuando no puede determinar si una línea es un problema (un tamaño pequeño en lo que podría ser una etiqueta), y tú puedes aumentarla cuando tu revisión muestre daño real.

ID	Regla	Gravedad	Grado	Referencia
type-rem-zoom	El texto debe sobrevivir al zoom. Tamaños en rem, sin tamaños de fuente solo de viewport, zoom nunca deshabilitado.	error	standard	typography
contrast-floor	Cada par de texto al menos 4.5:1. Texto grande y partes de UI al menos 3:1.	error	standard	contrast-and-color
contrast-color-alone	Nunca señales estado solo con color.	error	standard	contrast-and-color
motion-flash	Nada parpadea más de tres veces por segundo.	error	standard	motion
motion-autoplay	Sin vídeo de reproducción automática sin controles. Cualquier cosa que se mueva durante más de 5 s junto al texto necesita pausa. Sin bucles infinitos junto al texto.	error	standard	motion
motion-reduced	El movimiento existe solo dentro de prefers-reduced-motion: no-preference.	error	standard	motion
theme-focus	Nunca elimines el contorno de enfoque sin un reemplazo visible de al menos 3:1.	error	standard	theming
type-body-size	Texto del cuerpo 1rem mínimo, 1.125rem a 1.25rem para lectura larga. Nada legible por debajo de 0.875rem.	warning	research	typography
motion-triggers	Sin paralaje, secuestro de desplazamiento o zoom de área grande. Las transiciones y cambios de color están bien.	warning	research	motion
contrast-dark-secondary	Texto secundario sobre superficies oscuras a 8.5:1 o mejor. AA solo se lee débil ahí.	warning	inference	contrast-and-color
contrast-saturated-on-dark	Sin rojo o azul saturado como texto pequeño sobre oscuro. Acentos más claros y tranquilos en temas oscuros.	warning	research	contrast-and-color
lum-section-steps	Sin secciones alternas de oscuro y blanco a sangre completa. Sin incrustaciones o modales blancos en un tema oscuro.	warning	inference	layout-and-patterns
lum-white-flash	Fondo html con tema y una declaración color-scheme y metaetiqueta.	warning	convention	theming
layout-shift	Reserva dimensiones de medios, iguala las métricas de fuentes de respaldo, mantén CLS en o por debajo de 0.1.	warning	research	layout-and-patterns
contrast-pure-extremes	Casi negro sobre casi blanco, blanco roto sobre gris oscuro. Evita el negro puro y el blanco puro como texto de página y fondo.	warning	convention	contrast-and-color
type-leading	line-height del cuerpo 1.5 (1.4 a 1.6). Encabezados 1.1 a 1.3.	warning	convention	typography
type-weight	Peso del cuerpo 400 o más. Sin 100 a 300 en tamaños de cuerpo.	warning	convention	typography
type-align	text-align: start. Sin texto del cuerpo justificado. Mayúsculas solo para etiquetas cortas.	warning	standard	typography
layout-targets	Objetos de puntero mínimo 24 por 24 píxeles CSS, 44 por 44 para acciones primarias. Los enlaces dentro de una oración están exentos.	warning	standard	layout-and-patterns
theme-both-schemes	Implementa claro y oscuro y sigue prefers-color-scheme. Un conmutador manual es opcional y por defecto sigue al sistema.	note	research	theming
pattern-stripes	Sin rayas o rejillas de alto contraste con un período de 7 a 27 píxeles en áreas grandes.	note	inference	layout-and-patterns
type-measure	Texto de lectura limitado a 50ch a 60ch, que es aproximadamente 65 a 78 caracteres.	note	convention	typography
motion-duration	100 a 300 ms, techo de 500 ms, ease-out para entradas.	note	convention	motion
theme-preferences	Respeta prefers-contrast, forced-colors y prefers-reduced-transparency.	note	convention	theming
pattern-clutter	Un énfasis primario por vista. Pocos colores de acento, tamaños y estilos de borde.	note	research	layout-and-patterns
craft-copy	Texto específico. Nunca inventes estadísticas, testimonios, valoraciones o logotipos de clientes.	warning	convention	craft
craft-reference	Estudia de tres a cinco sitios reales en la misma categoría antes de diseñar. Toma prestadas decisiones, nunca copies.	note	convention	craft
craft-one-idea	Una idea distintiva por vista. Todo lo demás permanece tranquilo.	note	convention	craft
craft-palette	Neutros matizados y un acento. Sin degradados de índigo o púrpura, sin texto degradado.	note	convention	craft
craft-show-product	Muestra la interfaz, los datos o el código reales. Sin fila de tres tarjetas de iconos idénticas, sin iconos emoji.	note	convention	craft
craft-layout	No centres todo. Divisiones de rejilla desiguales y estructura de secciones variada.	note	convention	craft
craft-restraint	Superficies planas y líneas finas. Pocas sombras, una escala de radio, sin desenfoque y brillo apilados.	note	convention	craft

Los archivos de referencia contienen el razonamiento, las fuentes y el código antes/después. Lee cada uno que cubra una regla que estés aplicando o reportando. Una corrección en una página completa generalmente necesita tres o cuatro de ellos.

• references/contrast-and-color.md: elegir colores, construir una paleta o un tema oscuro, explicar un hallazgo de contraste.
• references/typography.md: tamaño de tipo, longitud de línea, espaciado, fuentes, tipo fluido.
• references/motion.md: animación, transiciones, vídeo, efectos de desplazamiento, cargadores.
• references/layout-and-patterns.md: tablas, rejillas, rayas, densidad, fondos de sección, imágenes, cambio de diseño.
• references/theming.md: temas claro y oscuro, un conmutador de tema, estilos de enfoque, consultas de medios de preferencia del usuario, Tailwind y shadcn/ui.
• references/craft.md: diseñar una nueva página o sección, un resultado que parezca plantilla o generado, qué tomar prestado de un sitio de referencia y qué dejar.
• references/evidence.md: cuando el usuario pregunta por qué, cuestiona una regla, o pregunta sobre luz azul, modo oscuro, fuentes para dislexia o APCA.

Valores por defecto para escribir sin que te lo pidan

:root {
  color-scheme: light dark;
  --bg:     light-dark(oklch(0.985 0.002 90), oklch(0.18 0.01 255));
  --text:   light-dark(oklch(0.24 0.01 255),  oklch(0.93 0.005 255));
  --muted:  light-dark(oklch(0.48 0.01 255),  oklch(0.78 0.01 255));
  --accent: light-dark(oklch(0.5 0.19 255),   oklch(0.74 0.13 255));
}
html { background-color: var(--bg); color: var(--text); }
body { font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem); line-height: 1.6; }
p, li { max-inline-size: 55ch; }
:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
@media (prefers-reduced-motion: no-preference) {
  .card { transition: transform 200ms ease-out; }
}

Agrega <meta name="color-scheme" content="light dark"> a la cabecera de la página.

El texto del cuerpo mide 15.75:1 en claro y 15.30:1 en oscuro. El texto atenuado mide 6.25:1 y 9.39:1. El acento mide 5.78:1 y 8.14:1, por eso se usa para el anillo de enfoque: el color Highlight del sistema puede caer por debajo de 3:1 en una superficie oscura. assets/tokens.css tiene el conjunto completo, incluyendo superficies, bordes para controles, un tamaño para lectura larga y un tema atenuado opcional.

Solo agrega color-scheme: light dark una vez que la página realmente tenga colores para ambos esquemas. En una página con colores claros codificados, da barras de desplazamiento oscuras y controles de formulario en una página blanca. Corrige theme-both-schemes en el mismo cambio.

Tailwind y shadcn/ui envían blanco puro con casi negro (aproximadamente 19.8:1) y bg-white / text-black como valores puros. Sobrescribe --background y --foreground, y usa utilidades semánticas como bg-background y text-foreground.

Lo que el script no puede ver

inspect.mjs cubre el primer, tercer y quinto elemento a continuación cuando puedas ejecutarlo en la página renderizada. Verifica el resto, y todos ellos cuando no se haya podido ejecutar, leyendo el código o la página. Si no puedes verificar uno, colócalo bajo "No verificado" y explica por qué.

• Contraste de cada par de texto y fondo real, incluido el texto sobre imágenes y degradados. Mide los pares con el comando contrast
• Si el texto pequeño es copia del cuerpo o una etiqueta corta
• Longitud de línea en el diseño renderizado. Cuenta caracteres en algunas líneas completas
• Velocidad de destello de animaciones y vídeo
• Saltos de brillo entre secciones e incrustaciones blancas dentro de temas oscuros
• Cambio de diseño durante la carga, incluyendo imágenes y vídeo sin width y height
• Si el estado se transmite solo por color
• Animación controlada por JavaScript que ignora el movimiento reducido
• Tamaños establecidos en em, porcentajes o la abreviatura font, y rayas construidas con background-size

Plantilla de informe

Fácil para los Ojos

Auditoría de <ruta>

---

<ID de regla>  <gravedad>
  <explicación>

Para cada hallazgo, escribe el ID, la gravedad y una frase. Cuando corrijas, explica qué cambiaste.

Instalación

Esta skill está diseñada para asistentes de IA. Consulte la documentación de su plataforma para obtener instrucciones de instalación.