Ely Componentes

---
name: ely-ui-components
description: Implement functional frontend components with explicit interaction contracts, keyboard behavior, forms, and meaningful loading, empty, error, and success states. Use to turn UI mockups into working controls or repair incomplete component behavior within an existing design system.
---

# Ely Componentes

Convertir una interfaz en controles que respondan de forma predecible. Respetar la biblioteca, los patrones visuales y el modelo de datos existentes. La apariencia no reemplaza un contrato de interacción y la skill no presupone un backend disponible.

## Definir el contrato antes de estilizar

Para el componente solicitado, identificar qué tarea resuelve, qué inicia cada acción, dónde vive su estado y qué resultado observa la persona. Inspeccionar componentes parecidos y las primitivas ya instaladas antes de crear otra abstracción o añadir dependencias.

Separar estado de dominio —por ejemplo, pedido confirmado— de estado transitorio de interfaz —envío pendiente—. Elegir una fuente de verdad; evitar copias locales de props que se desincronizan. Exponer solo las variantes y eventos que los consumidores reales necesitan.

Usar enlaces para navegar, botones para actuar y controles nativos cuando expresen la tarea. Comprobar si realmente hace falta un widget complejo: un conjunto de enlaces no necesita convertirse en un menú ARIA. Si se usa una primitiva existente, conservar su gestión de foco, atributos y contrato al personalizarla.

Leer [references/interaction-contracts.md](references/interaction-contracts.md) cuando haya formularios, overlays, selección o datos asíncronos. Elegir las filas pertinentes; no añadir todos los estados o patrones a un componente que no los necesita.

## Implementar el recorrido completo

- Nombrar cada control según su acción u objeto. Dar nombre accesible a botones de icono, asociar etiquetas con campos y conservar instrucciones necesarias fuera del placeholder.
- Distinguir hover, foco, activo, seleccionado y deshabilitado cuando correspondan. Mantener el foco visible. No deducir selección exclusivamente de color ni simular deshabilitado con opacidad.
- Hacer que la activación por teclado produzca el mismo resultado que la activación por puntero. Para widgets compuestos, seguir el patrón de la primitiva o documentación oficial pertinente; no inventar combinaciones de teclas.
- En operaciones pendientes, comunicar qué está ocurriendo y evitar envíos duplicados cuando generarían acciones duplicadas. Conservar los datos introducidos. Permitir que la persona continúe con acciones independientes si es útil.
- Distinguir ausencia de datos de un fallo al obtenerlos. En un error, explicar qué acción puede recuperar el flujo y conservar contexto; no mostrar un estado de éxito sin confirmación real.
- Aplicar actualizaciones optimistas solo cuando el dominio tolere reversión y exista una recuperación implementada. Evitar respuestas asíncronas obsoletas que reemplacen una selección o consulta más reciente.
- Comunicar cambios dinámicos relevantes sin anuncios repetitivos. Usar regiones de estado para resultados que no mueven el foco; reservar alertas intrusivas para situaciones que justifican interrumpir.

Si falta una integración, implementar el recorrido local que el alcance permita e identificar claramente datos de demostración. No presentar un botón como envío, pago o suscripción funcional cuando solo cambia un mensaje local. No inventar endpoints ni autorización para escribir en servicios externos.

## Componer sin perder comportamiento

Mantener decisiones de negocio fuera de primitivas visuales reutilizables cuando varios consumidores necesiten reglas diferentes. Una API de componente debe hacer explícitas las combinaciones válidas; evitar docenas de booleanos que permitan estados imposibles.

Comprobar que capas decorativas y animaciones no bloquean controles ni esconden el elemento enfocado. Una animación puede acompañar un cambio de estado, pero su finalización no debería ser la única vía para confirmar una acción o acceder al contenido. Coordinar con la animación de scroll existente cuando corresponda, conservando acceso a cada acción significativa.

## Verificar comportamientos observables

Recorrer el camino principal y una recuperación relevante: cancelar, corregir validación, reintentar o cambiar de selección durante una carga. Comprobar teclado, nombre del control, foco tras abrir/cerrar y estado final visible según el patrón. Para una lógica asíncrona o combinación de estados con riesgo real, agregar una prueba enfocada en el comportamiento, aprovechando las herramientas del proyecto.

Entregar qué controles funcionan, qué integración utilizan y qué recorridos se comprobaron. Distinguir una revisión por teclado de una prueba con lector de pantalla; no afirmar accesibilidad completa a partir de una sola herramienta. Esta skill es autónoma y no exige un rediseño, otras skills ni publicación.