Generar una página con IA no es difícil; lograr que la segunda y tercera mantengan colores, espaciado, estados de componentes, accesibilidad y límites de interacción sí lo es. Astryx es el sistema de diseño React de código abierto de Meta. Su repositorio oficial lo describe como Beta y ofrece más de 150 componentes accesibles, temas, modo oscuro, plantillas y CLI, con sobrescritura de temas mediante propiedades personalizadas CSS. Repositorio oficial
Conectar Astryx a un Agent no busca que el modelo diseñe libremente: busca que personas y Agent usen los mismos componentes y documentación.
Decide primero si conviene introducirlo
Suele encajar cuando:
- Un proyecto React ya tiene varias páginas administrativas y la UI generada por IA empieza a desviarse.
- El equipo necesita unificar botones, formularios, diálogos, estados vacíos y modo oscuro.
- Se quiere que el Agent componga componentes existentes en vez de escribir CSS desde cero.
- Se puede validar y fijar una dependencia Beta de forma aislada.
Si no es React o ya existe una biblioteca interna madura, no refactorices por tendencia. Traslada prácticas de componentes primero, tokens primero y validación por capturas al sistema actual.
Instalación y tema mínimo
Los nombres de paquete del ejemplo oficial son:
|
|
Primero valida build, carga de estilos y modo oscuro en una rama aislada o página pequeña, y después amplíalo al punto de entrada. No dejes que un Agent sustituya estilos globales, el shell de rutas o archivos token existentes.
El tema debe expresar restricciones de marca, no permitir que cada página se sobrescriba libremente. Escribe en las reglas del proyecto qué colores, radios, tipografía y espaciado se pueden cambiar para que el Agent sepa qué reutilizar.
Empieza con una página pequeña, no con el shell de la aplicación
Elige una sola ruta, por ejemplo ajustes, barra lateral de filtros o tarjeta de detalle. Enumera su tipografía, espaciado, tokens de color, estados y componentes, y pide al Agent reconstruir una zona con Astryx. Conserva rutas, solicitudes de datos, comprobaciones de permisos y entrada de estilos globales; el sistema de diseño se ocupa de componentes y temas, no de migrar negocio.
Fija la validación local: instala dependencias e inicia el servidor, revisa modo claro y oscuro, recorre formularios, diálogos y botones con Tab, estrecha la ventana a ancho móvil y ejecuta pruebas o build existentes. Registra problemas en el cambio del componente para no descubrir conflictos de tokens, prioridad CSS o foco después de migrar muchas páginas.
Cuando la página sea estable, úsala como referencia: documenta paquetes permitidos, entrada de tema, estilo de importación y archivos globales intocables. Las tareas posteriores deben apuntar a ella.
Restricciones de proyecto para un Agent
Coloca reglas como estas en AGENTS.md, CLAUDE.md o un Skill:
|
|
Es más ejecutable que «haz un panel con el sistema de diseño»: da prohibiciones, una ruta de reutilización y entregables, y permite revisar si se evitó la biblioteca.
Escribe entradas, salidas y prohibiciones en la tarea
Una tarea real debe indicar alcance de página, datos utilizables, archivos editables y capturas requeridas. Por ejemplo: modificar solo src/features/orders/FilterPanel.tsx; reutilizar parámetros de consulta; no añadir dependencias ni cambiar rutas o theme.ts; entregar capturas de escritorio y estrecha y enumerar estados de Button, Select y Dialog. Así el Agent no cambia reset global, gestión de estado o API solo para lograr una apariencia.
En componentes complejos, pide primero un borrador estructural: secciones, componente Astryx correspondiente y estados loading/error/empty. Aprueba la estructura antes del código. Si el diseño excede la biblioteca, ajusta el diseño o asigna responsable al componente nuevo, no añadas CSS desechable.
Cuatro capas de aceptación para reducir deriva de UI
| Capa | Qué revisar |
|---|---|
| Componentes | Si reutiliza Button, Input, Dialog y similares, con estados completos |
| Tema | Si los cambios visuales usan solo tokens o variables CSS permitidos |
| Interacción | Si foco de teclado, loading, error y vacío son utilizables |
| Entrega | Si build pasa, capturas cubren páginas clave y existe lista de componentes |
La coherencia visual no es copiar píxeles. Deben mantenerse semántica accesible, máquinas de estado, origen del tema y límites de componentes mantenibles.
Un proceso de aceptación repetible
Antes de fusionar, revisa el diff por estilos globales que eviten la biblioteca, colores de marca escritos fijos y archivos no relacionados. En el navegador prueba datos normales, carga, datos vacíos y fallo de API; en formularios prueba obligatorio, formato erróneo, deshabilitado y envío. Una captura del estado normal oculta la mayoría de regresiones.
Por último, completa un flujo clave con teclado: el orden Tab debe tener sentido, el foco debe entrar y salir de Dialog, los mensajes de error deben asociarse al campo y el contraste de color debe ser suficiente. Inclúyelo en la plantilla de PR para que las páginas generadas por Agent reciban el mismo estándar.
Errores comunes
- Tomar Beta como motivo para rehacer todo el sitio: fija versión y valida coste de actualización en un área primero.
- Dejar que el Agent edite internals de componentes: prioriza composición y tema; toma el código solo si es necesario.
- Escribir CSS temporal por página: el sistema queda como un nombre de paquete y no condiciona a futuros Agent.
- Validar solo capturas: no muestran orden tab, feedback de error ni botones no pulsables.
Resumen
Astryx ayuda a establecer un lenguaje de frontend compartido por personas y Agent. Valida componentes, tema y aceptación en pocas páginas, y después consolida las reglas en archivos del proyecto; no conviertas el nuevo sistema en otra abstracción sin mantenimiento.