Cómo conectar frontends generados por IA a un sistema de diseño con Astryx: componentes React, temas y criterios de aceptación

Sun, 12 Jul 2026 12:15:00 +0800

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:

1
2

npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

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:

- 新页面优先使用 @astryxdesign 现有组件；新增自定义组件前先说明原因。
- 不新增全局 CSS reset，不修改既有主题 token。
- 所有表单字段必须有可见 label、错误态和禁用态。
- 完成后提供桌面和窄屏截图，并列出新增组件与交互状态。
- 不以截图相似为唯一验收；保留键盘操作和语义结构。

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.

Design System on KnightLi Blog