spnngl/agent-skills

Experto en UI

Esta habilidad decide cómo es la interfaz y demuestra que funciona para las personas. Los modismos de código (TypeScript, React, Next.js, tests, lint) provienen de la habilidad ts-coding: cárgala cada vez que toques un archivo .ts o .tsx.

Flujo de trabajo

1. Orientar. Lee las fuentes de verdad de la UI: package.json (react, next, tailwindcss, la librería de primitivas: react-aria-components, @radix-ui/*, @base-ui-components/react, o el components.json de shadcn; el set de iconos; @playwright/test, @axe-core/playwright), la hoja de estilos que contiene @import "tailwindcss" y @theme, el mecanismo de modo oscuro, el directorio de componentes compartidos y dos o tres pantallas existentes junto a la que estás cambiando. Las decisiones existentes del proyecto tienen prioridad sobre los valores predeterminados de esta habilidad; reutiliza sus primitivas, tokens, ritmo de espaciado y terminología. Listo cuando: puedas nombrar el sistema de estilos, el archivo de tokens, la librería de primitivas, el set de iconos, el interruptor de tema, el comando de desarrollo y la URL que renderizan el trabajo, y el ejecutor de pruebas del navegador (o que no existe ninguno).

2. Definir el brief. Antes de cualquier marcado, escribe este bloque en tu respuesta y constrúyelo:

   Usuario y tarea:   quién usa esto y la única tarea que sirve
   Foco principal:    el elemento único en el que la vista se posa primero
   Acción primaria:   la única acción afirmativa; las acciones destructivas se nombran por separado
   Densidad:          disperso | cómodo | denso, adaptado a las pantallas vecinas
   Tono:              un adjetivo que el resultado debe merecer ("preciso", "tranquilo", "cálido")
   Estados:           vacío, cargando, error, parcial, desbordamiento, sin permiso: aquellos que apliquen
   

   Diseño, composición y artesanía visual: references/taste.md. Listo cuando: cada campo tenga una respuesta concreta para esta pantalla, lo suficientemente específica como para que un revisor pueda rechazar una construcción que no la cumpla.

3. Resolver tokens. Asigna cada color, tamaño, espacio, radio, sombra y duración a un token semántico del paso 1. Añade un token faltante en la fuente con valores claro y oscuro, siguiendo references/tokens.md. Listo cuando: el diff no contenga colores brutos, valores arbitrarios (p-[13px], bg-[#1a1a1a]) o estilos en línea para una propiedad tematizable, cada nuevo token tenga un valor claro y uno oscuro, y node scripts/contrast.ts <tema.css> (ruta relativa al directorio de esta habilidad) pase.

4. Construir. Compón a partir de las primitivas del proyecto (React Aria Components cuando no tenga ninguna), mobile-first, siguiendo las Reglas y references/components.md. Semántica, teclado y detalle WCAG: references/accessibility.md. Texto de interfaz: references/copy.md. Listo cuando: cada elemento interactivo cubra cada estado que aplique, cada vista de datos renderice cada estado nombrado en el brief, y los estilos sin prefijo sean el diseño de 320px.

5. Verificar. Ejecuta las comprobaciones de ts-coding, luego las puertas estáticas y del navegador en references/verification.md: desviación de tokens, emoji, contraste de tokens, axe en claro y oscuro, teclado, reflujo a 320px, tamaño de objetivo, movimiento reducido. Listo cuando: cada puerta termine con código 0 e informes lo que cada una imprimió; una puerta que no pudiste ejecutar se reporta como "no verificado" con el motivo.

6. Observar. Captura la pantalla a 1280 y 390 de ancho, claro y oscuro, más cada estado del brief; abre cada imagen con la herramienta de lectura y haz clic en cada control. Luego argumenta para el rechazo con references/review.md. Cuando una herramienta de subagente esté disponible, pasa las capturas de pantalla y ese archivo a un agente nuevo: un crítico que no construyó la pantalla la ve con más claridad. Listo cuando: hayas visto cada captura de pantalla, cada control haya producido un cambio visible y cada hallazgo Crítico o Mayor esté corregido o reportado al usuario.

Cambios pequeños (un ajuste de espaciado, color o texto dentro de un componente existente): ejecuta los pasos 1, 3 y las puertas estáticas del paso 5, luego captura el elemento cambiado en claro y oscuro y mira ambos.

Revisar UI existente: ejecuta el paso 1, escribe el brief del paso 2 según lo infieras, ejecuta los pasos 5 y 6 sobre ello e informa en el formato de references/review.md. Sin un renderizado, dilo y limita los hallazgos a lo que la fuente demuestre.

Reglas

Evidencia

• Indica una relación de contraste, un aprobado o una puntuación solo cuando un comando acabe de imprimirlo; de lo contrario, di "no verificado". Una puerta que se saltó (sin navegador, sin servidor) no midió nada.
• Las puertas demuestran corrección, nunca calidad: juzga jerarquía y artesanía a partir de las capturas de pantalla.

Jerarquía

• Un elemento domina: el foco principal del brief es el elemento más grande, más pesado o de mayor contraste, y sus pares se vuelven más silenciosos. En páginas de marketing y aterrizaje, el texto de exhibición es al menos 2.5 veces el tamaño del cuerpo; las pantallas de producto mantienen el título de página uno o dos pasos por encima del cuerpo, con el peso y la posición haciendo el resto.
• El espaciado crece hacia afuera: los espacios dentro de un grupo < el relleno de su contenedor < el espacio entre secciones.
• Un estado vacío llena su región y nombra la primera acción. Una página termina con un propósito: un resumen, un pie de página, un siguiente paso.

Tokens y color

• Token por intención: elige el token cuyo significado coincida con la acción. Una acción destructiva lleva el token destructivo tanto en su disparador como en su confirmación; el primario marca la única acción afirmativa principal por vista.
• Cada estado empareja color con un icono o texto. Un acento; los neutros llevan el resto.
• La tematización es una edición en la fuente del token: cada pantalla lee los mismos tokens semánticos.
• Claro y oscuro siguen la preferencia del sistema; una configuración Sistema / Claro / Oscuro lo anula y persiste (references/tokens.md).

Estados

• Elementos interactivos: predeterminado, hover, focus-visible, presionado, deshabilitado, pendiente, inválido, seleccionado. Cada uno que aplique es visualmente distinto, en claro y oscuro; selectores en references/components.md.
• Pendiente mantiene el control a plena potencia con un spinner o etiqueta de progreso (isPending, aria-busy). Deshabilitado marca una acción que el usuario no puede tomar ahora, con el motivo visible cerca.
• La retroalimentación reporta lo que sucedió: un toast de éxito aparece después de que los datos cambiaron, y la vista ya muestra el cambio.

Diseño

• Móvil es la base: las utilidades sin prefijo son el diseño de teléfono; sm:, md:, lg: se superponen en pantallas más anchas. Los componentes reutilizados en diferentes anchos responden a su contenedor (@container, @md:).
• Una región que se desplaza horizontalmente muestra una señal visible: un degradado de borde, una barra de desplazamiento.

Barreras de protección

• Los iconos provienen de lucide-react (o del set del proyecto) como SVG con currentColor. Cero emojis en UI, copy, código y commits.
• Las superficies se separan con un borde completo de un píxel, un paso de superficie o espaciado. Está prohibido un borde de color en un solo lado de una tarjeta, alerta, toast o llamada a la acción.
• El contenido es realista: nombres plausibles, cadenas largas, números grandes, cero y un elemento. El texto de relleno y los controles de depuración nunca se renderizan en el producto.

Referencias

Carga la que coincida con la rama en la que estés:

• references/taste.md: indicios de slop, composición, tipografía, color, profundidad; cualquier pantalla nueva o rediseño.
• references/tokens.md: @theme de Tailwind v4, tokens semánticos, tema del sistema y su configuración de anulación, añadir o auditar tokens.
• references/components.md: React Aria Components, atributos de estado, formularios, superposiciones, vistas de datos, iconos, animación.
• references/accessibility.md: semántica, teclado y foco, contraste, criterios WCAG 2.2, colores forzados, RTL.
• references/copy.md: etiquetas, errores, estados vacíos, confirmaciones, toasts, indicios de copy generado.
• references/verification.md: escaneos de desviación, emoji y contraste, renderizado de estados de componentes, puertas de Playwright y axe, matriz de capturas de pantalla.
• references/review.md: lentes de crítica, heurísticas, gravedad, formato de hallazgos.