Communitygithub.com

better-ui

Pule superficies, iconos y animaciones con valores exactos para bordes redondeados, alineación óptica, sombras, estados de iconos y animación.

¿Qué es better-ui?

El skill **better-ui** se especializa en el pulido visual de interfaces de usuario, proporcionando valores exactos y recetas detalladas para elementos como bordes redondeados, sombras, alineación óptica, escalas de presión, transiciones de iconos y animaciones de entrada/salida. Está diseñado para usarse después de que la interacción subyacente sea sólida, asegurando que el pulido nunca reemplace una interacción rota. Compatible con cualquier framework o librería de componentes (CSS puro, Tailwind, Motion), ofrece directrices precisas como `cubic-bezier(0.2, 0, 0, 1)` para transiciones, escalas de `0.96` en botones presionados, y sombras para elevación en lugar de bordes. Además, promueve la accesibilidad mediante el respeto a `prefers-reduced-motion` y la supresión de transiciones durante cambios de tema. Incluye una tabla de detección de problemas comunes con soluciones claras y un sistema de reporte basado en severidad (HIGH, MEDIUM, LOW) para facilitar la revisión manual o automatizada.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Atou4/skillsmith/tree/HEAD/skills/ui-ux/better-ui

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Pulido de UI

Este skill contiene el pulido visual de superficies, iconos y animaciones, con el valor exacto que cada detalle requiere. Se aplica una vez que la interacción subyacente es sólida, y un hallazgo de pulido nunca supera a una interacción rota.

Valores exactos, pulido opcional

Los valores siguientes son exactos, no rangos para aproximar. cubic-bezier(0.2, 0, 0, 1) no es cubic-bezier(0.4, 0, 0.2, 1), y 0.96 no es 0.95. Los ajustes ópticos y el límite de relleno concéntrico son las excepciones. Son puntos de partida, juzgados visualmente.

Mantén la librería de componentes, tokens y densidad del proyecto, y respeta su lenguaje de movimiento en todas partes donde no haya una regla que proporcione un valor. Una convención deliberada y consistente del proyecto, como un estilo sin sombras, es una preferencia y no un hallazgo. El mismo detalle hecho de dos maneras diferentes dentro del proyecto es un hallazgo.

El ajuste de texto, el renderizado de fuentes, los números tabulares y el espaciado de texto pertenecen a better-typography. Las áreas de impacto, el soporte de teclado, ARIA y el requisito de movimiento reducido pertenecen a better-accessibility. La agrupación, el espaciado entre secciones, los puntos de quiebre y el RTL espacial pertenecen a better-layout, excepto el espejado direccional de iconos. Los tokens de color y la medición de contraste pertenecen a better-colors.

El radio exterior es igual al radio interior más el relleno

Donde las superficies anidadas comparten un margen interior visible y uniforme, el radio exterior es el radio interior más el relleno más cualquier ancho de borde. Más allá de 24px de relleno, o donde el relleno es deliberadamente asimétrico, trata las capas como superficies separadas y mantén el token de radio de cada una. Las recetas están en superficies.md.

Alinea ópticamente donde la geometría se ve mal

Donde el centrado geométrico se ve incorrecto, ajusta visualmente. Dale a un botón 2px menos de relleno en su lado del icono, desplaza un triángulo de reproducción hacia su punta y corrige glifos asimétricos en el propio SVG. Las recetas están en superficies.md.

Sombras para elevación, bordes para estructura

Donde un borde existe solo para crear profundidad, reemplázalo con valores de box-shadow transparentes y en capas. Mantén los bordes en divisores, separadores, celdas de tabla y estados seleccionados. También mantenlos en las entradas de formulario, cuyo límite necesita un contraste no textual de 3:1 según better-accessibility. Los anillos de enfoque también pertenecen a better-accessibility.

El modo de colores forzados elimina todas las box-shadow. Mantén border: 1px solid transparent debajo de un anillo de sombra para que ese modo aún dibuje un borde. Las recetas están en superficies.md.

Delinea imágenes en negro puro o blanco puro

A las imágenes de contenido dales un outline de 1px insertado en 1px. Usa oklch(0 0 0 / 0.1) en modo claro y oklch(1 0 0 / 0.1) en modo oscuro. Nunca uses una paleta casi negra, un neutro matizado o el color de acento, porque el matiz se muestra como una franja de color en el borde de la imagen. Omite gráficos transparentes como logotipos e ilustraciones. La receta está en [superficies.md](superficies.md# delineados-de-imagen).

Transiciones, no keyframes, para el estado interactivo

Impulsa los cambios de estado interactivos con transiciones CSS o los springs de una librería de animación, que se redirigen cuando el usuario revierte a medio camino. Los keyframes ejecutan una línea de tiempo fija y no pueden revertir, así que resérvalos para secuencias que se ejecutan una sola vez. Consulta animaciones.md.

La escala de presión es 0.96

Un botón presionado se escala a 0.96 durante 150ms con ease-out, y uno deshabilitado nunca se escala. Dale al botón una opción de exclusión donde el movimiento distraería, a través de la API de variantes existente del componente o una prop static. Consulta las recetas para CSS, Tailwind y Motion.

Las interacciones de alta frecuencia responden instantáneamente

Las pulsaciones de teclas, los hover de filas y los cambios de pestaña reciben retroalimentación instantánea, o una transición de 150ms o menos en opacity o background-color. Reserva el movimiento expresivo para momentos poco frecuentes, como la primera carga de una vista, un estado de éxito o un estado vacío.

Cada cambio de estado animado también deja una pista estática en forma de color, icono o etiqueta. El movimiento nunca es el único canal de retroalimentación.

Controla el movimiento con la preferencia de movimiento reducido

better-accessibility es dueña del requisito, y ninguna receta aquí se entrega sin él. Ejecuta movimiento, escala y desenfoque solo bajo prefers-reduced-motion: no-preference. Bajo movimiento reducido, reemplázalos con un fundido cruzado de opacidad en lugar de eliminar el elemento instantáneamente. Las recetas para CSS, Tailwind y Motion están en animaciones.md.

Escalonar las entradas poco frecuentes en 100ms

Donde la secuencia comunica jerarquía en una entrada escalonada, divide el contenido en fragmentos semánticos como título, descripción y acciones. Escalónalos con 100ms de separación, cada uno entrando con opacidad, 4px de desenfoque y 12px de translateY durante 300ms con ease-out. Nunca escalones interacciones rutinarias. Consulta entrada-salida.md.

Las salidas son más cortas y más pequeñas que las entradas

Sal con opacidad, 4px de desenfoque y un translateY fijo de -12px durante 150ms con ease-out, nunca la altura completa del contenedor. Desliza completamente hacia afuera solo donde el destino tenga significado, como al cerrar un cajón. Elimina el elemento instantáneamente donde el movimiento no añada información. Consulta entrada-salida.md.

Omitir animaciones de estado en el primer renderizado

Establece initial={false} en un AnimatePresence que envuelva un intercambio de estado, para que el estado predeterminado no se anime al montarse. Nunca lo establezcas alrededor de una entrada intencional como un héroe escalonado. Consulta animaciones.md.

Fundido cruzado de iconos contextuales con valores exactos

Donde un icono cambia en un cambio de estado poco frecuente, como reproducir a pausa o copiar a copiado, haz un fundido cruzado. La escala va de 0.25 a 1, la opacidad de 0 a 1 y el desenfoque de 4px a 0px. Con una librería de animación, usa { type: "spring", duration: 0.3, bounce: 0 }, y el rebote siempre es 0. Sin una, mantén ambos iconos en el DOM y haz un fundido cruzado durante 300ms con cubic-bezier(0.2, 0, 0, 1).

El intercambio de iconos de una pestaña y las acciones que una fila revela al pasar el ratón caen bajo Las interacciones de alta frecuencia responden instantáneamente. Ambas recetas están en transiciones-de-icono.md.

Suprime las transiciones en el cambio de tema

Deshabilita cada transición para el intercambio de tema, fuerza una actualización de estilo y restaura las transiciones después del siguiente cuadro. De lo contrario, cada transición de color se dispara a la vez y el cambio se mancha. Consulta la receta.

Transiciona solo lo que cambia

Nombra las propiedades exactas, como en transition-property: scale, opacity, y nunca all. Consulta rendimiento.md.

Nombra la propiedad animada en will-change

Añade will-change solo después de ver tartamudeo en el primer fotograma, y nombra la propiedad que animas: scale para scale, transform para transform. Limítalo a propiedades de transformación, opacity y filter, y nunca uses all. Consulta rendimiento.md.

Efectos hover solo en punteros con capacidad de hover

Pon los estilos solo para hover detrás de @media (hover: hover). En táctil, :hover se fija después de un toque y se lee como un estado seleccionado atascado. La variante hover: de Tailwind 4 ya compila bajo esa consulta, y la de Tailwind 3 no. Donde un control dibuja su propio estado presionado, establece -webkit-tap-highlight-color: transparent para que el destello gris predeterminado no lo duplique.

Contener el desplazamiento dentro de superposiciones

A los diálogos, cajones, menús y paneles laterales con desplazamiento dales overscroll-behavior: contain, para que desplazarse más allá de su final nunca desplace la página detrás.

Igualar el grosor del trazo del icono al peso del texto

El trazo renderizado de un icono sigue el peso del texto junto a él, desde 1.5px en 400 hasta 2.5px en 700. Usa una librería de iconos por superficie. La tabla, las reglas de tamaño y de cuadrícula están en iconos.md.

Un SVG, recolorizado por estado

Los iconos usan currentColor y toman los estados hover, seleccionado y deshabilitado del color y la opacidad de CSS, nunca de activos separados. El contorno es la variante predeterminada, y el relleno marca el estado activo. Bajo dir="rtl", refleja solo los iconos cuyo significado sigue la dirección de lectura. Consulta iconos.md.

Antes de terminar

DetecciónSolución
Padre e hijo con el mismo rounded-* o border-radius y rellenoAñade el relleno al radio exterior
Anillo box-shadow: 0 0 0 1px sin border al ladoborder: 1px solid transparent
outline-slate-*, outline-zinc-* o un color de contorno hexadecimal en imgoutline-black/10 y dark:outline-white/10
transition-all o transition: allNombra las propiedades que cambian
animation: establecido en :hover, .open u otra clase conmutadaUna transición en las mismas propiedades
active:scale-95, scale-90 o whileTap por debajo de 0.960.96
Escala :active sin exclusión :disabledenabled:active: o :not(:disabled):active
bounce: establecido en algo que no sea 0bounce: 0
opacity: 0 en una regla base que solo una animation revelaEstado oculto en el keyframe from, animation-fill-mode: both
Animación translate, scale, filter o motion.* sin prefers-reduced-motion, motion-safe: o protección MotionConfigProtégela y haz un fundido cruzado de opacidad bajo movimiento reducido
Transiciones de color más un interruptor de tema sin disableTransitionOnChange o anulaciónLa receta de supresión de cambio de tema
will-change: all, o will-change en un elemento que nunca animaNombra la propiedad animada o elimínalo
fill="#..." o stroke="#..." dentro de un SVG de iconocurrentColor
:hover en CSS plano o hover: de Tailwind 3 fuera de @media (hover: hover)Envuélvelo en la consulta
overflow: auto o overflow-y-auto en un diálogo, cajón o menú sin overscroll-behavioroverscroll-behavior: contain

Reporte

Gravedad. ALTA rompe una interacción, como un keyframe conmutable que no puede revertir o un estado hover atascado en táctil. Dos de los desencadenadores de escalada de better-interface caen aquí y son ALTA a primera vista. Uno es el movimiento que ignora prefers-reduced-motion, y el otro es un cambio de estado llevado solo por movimiento. MEDIA es una inconsistencia visible en superficies, iconos o movimiento. BAJA es pulido aislado.

Verificación. Sin navegador, lee cada estado que el componente define del código, como hover, presionado, seleccionado, cargando y vacío, con sus duraciones y easing. Con uno, recorre cada estado y reproduce la animación al 10% de velocidad en el panel Animaciones del navegador. Reporta cada verificación que no pudiste ejecutar como "No verificado".

Formato. Agrupa los hallazgos bajo el principio que cada uno viola, ordenados por gravedad, una fila por causa raíz listando cada ubicación donde aparece:

GravedadUbicaciónAntesDespuésPor qué

Ubicación es ruta/al/archivo:línea. Por qué nombra el principio y el impacto en el usuario.

Termina con Bloquear cuando quede alguna ALTA, Aprobar en caso contrario, dejando el resto en la tabla como trabajo pendiente. Nunca Aprobar una cobertura que no inspeccionaste. Sin nada que reportar, indica "No se encontraron hallazgos de pulido de UI procesables" y reporta la verificación.

Skills relacionados