Astryx auditado: el sistema de diseño de Meta con 14.522 estrellas midió cuatro veces su propia incorporación de agentes, y los suelos no coinciden

Astryx es el sistema de diseño que Meta cultivó durante ocho años en su interior y publicó como código abierto el 24 de junio de 2026. En 137 días acumuló 14.522 estrellas, 45 releases, 6.948 commits y 3.212 versiones publicadas de @astryxdesign/core en npm. Entrega 174 componentes, una CLI, siete temas, un servidor MCP remoto y una hoja de referencia para agentes de cuatro pantallas.

También entrega, en su propio README, una frase que dice cuánto crédito darle al marketing: la hoja de referencia ordena a los agentes de IA ejecutar npx astryx <cmd>, mientras que el README del paquete, seis líneas más abajo, advierte que el paquete astryx sin scope en npm pertenece a otra persona. Ambas afirmaciones están vivas en la v0.7.11. Solo una sobrevive a una instalación limpia.

Esta auditoría clona el repositorio, instala los paquetes publicados, ejecuta la CLI, llama al endpoint MCP, lee los registros de pruebas y reproduce el fallo que el propio proyecto documentó en un archivo marcado como «no implementado todavía» — y que resulta contener cuatro pilotos completos cuyos resultados se contradicen entre sí.

Es la tercera auditoría de esta serie en la que la instrumentación del proyecto, y no su README, decide el veredicto: gstack tenía un corpus de prompts compilado, agent-desktop tenía una tabla que negaba 44 de 60 comandos, y Auto-Ontology tenía un conector que devolvía la misma fila dos veces sin reportar error. La versión de Astryx de ese artefacto es un plan de experimentos.

La escala de la cosa

Antes de cualquier crítica: el volumen de ingeniería aquí no es normal para un sistema de diseño de código abierto.

Dos cifras merecen estar juntas. La proporción de pruebas frente a código dentro de packages/core/src es de 1,76:1 — no es un repositorio donde las pruebas se añadieron al final. Y 332 archivos llevan un .a11y. en el nombre: aproximadamente 1,9 especificaciones de accesibilidad por componente.

La cifra que no encaja: 13 envíos en Hacker News, con un máximo de 12 puntos, para un proyecto con 14.522 estrellas. Lo que produjo esas estrellas no fue el canal habitual de lanzamiento. El registro de npm lo cuenta mejor — 3.212 versiones en 137 días son 23 publicaciones al día, que es la forma que tiene el etiquetado canary por commit, y los dist-tags lo confirman (latest: 0.7.11, canary: 0.7.12-canary.f543ec7, más dos etiquetas históricas raras, bootstrap y vanilla-poc).

«Agent ready» como mecanismo, no como eslogan

La descripción en GitHub afirma que el sistema es «totalmente personalizable y agent ready». Lo de personalizable se comprueba fácil. Lo de agent ready solo significa algo si nombras los canales, así que aquí están los cuatro que existen y qué hace cada uno cuando instalas el paquete.

La mejor descripción del script postinstall la escribió el propio proyecto. De node_modules/@astryxdesign/core/scripts/postinstall.mjs:

Enforcement layer 1 of making astryx init foolproof: when the design system is installed and the project hasn’t run init yet, print a one-line next-step so agents/humans discover it (this is the most common fresh-install entry).

La capa de cumplimiento número 1 no se ejecutó en ninguna de mis dos instalaciones. npm 12.0.2 imprimió esto:

npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts:
npm warn install-scripts   @astryxdesign/core@0.7.11 (postinstall: node scripts/postinstall.mjs)

Es una política por defecto, no un error: los gestores modernos suprimen los scripts de instalación de dependencias. El proyecto lo sabe — sus propias notas de diseño mencionan pnpm 10 como el caso en que se saltan «los scripts de dependencias». Pero la capa se sigue llamando cumplimiento, y en la configuración que usa casi todo el mundo produce silencio.

La hoja de referencia que ejecuta el comando equivocado

Ejecuta astryx init en un proyecto vacío y obtendrás dos archivos: AGENTS.md (2.214 bytes) y GEMINI.md (55 bytes, un import de una línea). La línea interesante de AGENTS.md es la 7:

CLI: run every command as `npx astryx <cmd>` (shown below as `astryx ...`).

Ahora el README del paquete, en packages/core/README.md, por partida doble:

Always use the scoped name: the unscoped astryx resolves to an unrelated npm package until @astryxdesign/cli is a dependency.

Ambas son ciertas en su propio marco. Si @astryxdesign/cli es una dependencia del proyecto, npx astryx resuelve el binario local y funciona. Pero el trabajo de la hoja de referencia es justamente el caso en el que el lector todavía no lo sabe. En un proyecto que solo instaló @astryxdesign/core:

$ npx astryx component --list
npm error could not determine executable to run

Porque el astryx de npm — publicado el 2025-11-29 por un mantenedor ajeno, 120.089 bytes descomprimidos, sin campo bin, sin descripción, versiones 0.0.0 y 0.0.1-alpha.0 — no es una CLI. Meta nunca reclamó el nombre. La advertencia existe precisamente porque alguien tropezó con esto. El generador sigue emitiendo el comando sin calificar.

Hay una segunda señal de autoconciencia en la misma herramienta. La ayuda de astryx init --help dice, sobre su modo --user: «Warns, and still writes, when no astryx command on the computer runs the Astryx CLI». Es decir: la CLI puede detectar que el comando que recomienda no existe, y elige avisar en lugar de corregir la recomendación.

Canal 3: el aviso que nunca se construyó

De los cuatro canales, uno aparece en el propio plan de experimentos como la opción pasiva más fuerte. De internal/vibe-tests/cli-discovery-test/PLAN.md, la tabla de hipótesis:

H3 es el canal que sobreviviría a los dos problemas anteriores: es pasivo, viaja dentro del paquete y ninguna política de scripts de instalación puede suprimirlo. Nunca se implementó. En el paquete publicado @astryxdesign/core@0.7.11, cero de 1.101 archivos .d.ts contienen un aviso @see npx astryx. Los únicos tres que coinciden con @see.*astryx apuntan a una issue de GitHub (#1148), no a la CLI.

Lo que sí contienen esos archivos es un bloque JSDoc dirigido a quien trabaja dentro del monorepo de Meta:

* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Button/Button.doc.mjs
* - /packages/core/src/Button/Button.test.tsx

Inofensivo, pero revela para qué lector se optimizó el archivo. El plan llama a c2-types «el otro canal nativo para agentes» y lo lista como no probado en todas sus secciones de advertencias. No está en el artefacto publicado, y ninguna nota de release desde julio lo menciona.

Canal 4: el servidor MCP que funciona y nadie menciona

Aquí viene la sorpresa. El sitio de documentación afirma que los agentes pueden obtener documentación lista para agentes «desde la línea de comandos o MCP». La CLI no tiene comando mcp, y @astryxdesign/mcp, @astryxdesign/mcp-server y @astryx/mcp devuelven 404, así que la afirmación parecía marketing. No lo es. Hay un servidor MCP remoto por HTTP:

POST https://astryx.atmeta.com/mcp
initialize → serverInfo {"name":"astryx","version":"2.0.0"}, protocolo 2025-06-18
tools/list → 2.178 bytes, 2 herramientas

Las dos herramientas son search(query, limit) y get(name), y la salida es real. Medido el 2026-11-08:

Compáralo con la CLI local: astryx manifest --json pesa 88.788 bytes (40 veces el esquema de herramientas MCP), y astryx component Button son 10.029 bytes en texto plano frente a 13.040 por MCP — es decir, MCP cuesta un 30% más por componente y te ahorra la instalación entera. El flag --dense solo lo reduce a 8.666 bytes, un 13,6%, que no salvará la ventana de contexto de nadie.

Dos detalles del mismo endpoint. Las descripciones de las herramientas todavía dicen «Search Astryx (XDS) design system» — XDS era el nombre en clave interno, y una entrada del changelog dice que eliminar la nomenclatura xds de la API pública era un objetivo. Y la ruta de error está mejor diseñada que en la mayoría: una negativa de 123 bytes que nombra la siguiente herramienta a llamar.

El problema es la colocación. El AGENTS.md generado — el archivo cuyo único propósito es decirle a los agentes qué leer — no menciona MCP. Tampoco lo hace el aviso superior del README de core, que manda a los agentes a init. El único canal que no necesita instalación ni humano es el que las instrucciones para agentes omiten.

Sus propias mediciones, y los suelos que no coinciden

Aquí el repositorio merece crédito real y escrutinio real al mismo tiempo. Alguien construyó un arnés de experimentos serio para la pregunta del huevo y la gallina: en un proyecto que acaba de ejecutar npm install @astryxdesign/core sin que nadie corra init, ¿encuentra alguna vez el agente la CLI?

El diseño es mejor que el de la mayoría de los benchmarks publicados. La verdad de referencia sale del registro de un shim y no del autoinforme del agente, las condiciones se componen de una plantilla base desnuda más parches por canal, y cada ejecución ocurre en un sandbox aislado en /tmp con un cursor-agent headless. El primer piloto detectó su propia contaminación y tiró el resultado:

The funnel looked perfect — and that’s the trap. Ground-truth (shim log): c0 invoked 0/2, c5 2/2. A textbook floor/ceiling. It is a FALSE clean.

La contaminación era el CLAUDE.md del propio repositorio, que se aplica siempre y le enseñaba la CLI a los subagentes dentro del repo; un agente «desnudo» ejecutó 35 comandos astryx. Ese tipo de autopsia es lo bastante rara como para nombrarla.

Luego las ejecuciones siguieron, y esto es lo que contiene hoy PLAN.md — todas las cifras siguientes salen de ese archivo:

La sección de decisión, en mitad del archivo, se lee como una conclusión:

Ship the README callout (c1). 80% invoke + init — the only passive channel that triggers the persistent AGENTS.md install.

Y el piloto 3, añadido más abajo, dice que el suelo contra el que se midió no existe:

Why they tied: the agent reported howDiscovered: "readme" — the @astryxdesign/core README already ships a CLI section. So a “bare” install already advertises the CLI, and a capable agent finds + uses it unprompted.

La conclusión consolidada del final invierte la premisa original sin rodeos:

for a capable agent, CLI discovery is largely not the bottleneck — it already finds the CLI via the README, node_modules, or by guessing npx astryx. The shippable channels should help most for weaker agents/harnesses that don’t explore or read docs — which this pilot did not test.

Leído con cuidado, esto no es descuido. Es lo que parece la medición honesta cuando la hipótesis pierde: cuatro ejecuciones, cada una arreglando el defecto de la anterior, cada una encogiendo el efecto. El documento conserva las ejecuciones descartadas, conserva la contaminada etiquetada como «FALSE clean» y declara sus propias limitaciones (n=5, intervalo inferior del README ~38% frente al superior del suelo ~43%, un solo modelo, sin puntuación de calidad del código). La lección para el lector no es «falsificaron un benchmark», sino que el suelo de toda esta pregunta se movió de 0/5 a 2/2 a medida que el arnés se volvía más honesto, y nadie ha vuelto a derivar la decisión desde entonces.

Un detalle estructural que vale la pena: el archivo tiene dos secciones numeradas 15 y dos numeradas 16, y ha sido tocado por un único commit — 372d81b2, 2026-07-17, PR #4043 «feat(cli): make the CLI discoverable to AI agents». Todo el programa de descubrimiento ocurrió en las tres primeras semanas tras el lanzamiento y no se ha revisado en los 146 releases posteriores.

El registro está vacío y el de accesibilidad cubre 10 de 174

El repositorio incluye internal/vibe-tests/iterations.json. Su contenido completo:

{"iterations": []}

El arnés que produjo las tablas anteriores escribe su estado en otro sitio, o en ninguno. Eso importa porque el cuarto principio del README es:

Earned by measurement. We test conventions rather than assert them, hold the results loosely, and revisit them when a new situation proves them wrong.

La medición ocurrió — más de lo que pueden decir la mayoría de los proyectos. Simplemente vive en un documento de diseño marcado Status: proposal / design (not yet implemented) en la cabecera, que es lo primero que ve cualquier lector y lo último que se actualizó.

Las cifras de accesibilidad tienen la misma forma, con una brecha más filosa. El registro internal/vibe-tests/a11y-manifests/astryx.json se genera a partir de packages/core/src/*/README.md; es decir, de la prosa de los propios componentes, no de ejecuciones en navegador:

Diez de 174 componentes, sin documentación de teclado para nueve de esos diez, y solo dos nombres (Avatar, Button) coinciden con la base con la que se supone que se compara. El archivo se generó en febrero, cuando el paquete aún era privado, y está sellado como 1.0.0 mientras la versión publicada es 0.7.11. Mientras tanto el repositorio tiene 332 archivos .a11y.* y una puerta de Playwright (test:a11y-contract), así que las pruebas existen — lo que caducó es el resumen. Un lector no puede usar ese registro para decidir nada, y es exactamente a lo que recurriría primero.

«Guía antes que imposición», y 26 reglas privadas

El primer principio dice:

Guidance over enforcement. Components give you capability rather than guardrails that fight you.

Dentro del repositorio está internal/eslint-plugin-astryx, un plugin con 26 reglas documentadas que cubren colores en crudo, estilos codificados a mano, envoltorios solo de estilo, hover en estado deshabilitado, compartición del contorno de foco, keydown de IME sin protección y más. Su propio README abre con una doctrina que es lo más citable del código:

Agents should follow strict rules perfectly; they have no excuse for violations Humans need flexibility during development; warnings inform without blocking

Dos niveles: avisos para las personas, errores que rompen la compilación cuando CI=true o ASTRYX_STRICT_LINT=1. Es una respuesta coherente y con opinión al problema exacto que hoy enfrenta todo sistema de diseño. También es "private": true, versión 0.0.1, y no está en npm — los tres nombres que probé devuelven 404.

Así que la capa de imposición existe solo para quien ya trabaja en el monorepo. Los consumidores reciben guía, y sus agentes reciben lo que el modelo recuerde de una librería de componentes que nunca ha visto. Dado que las guías del mismo repositorio admiten que «los modelos todavía necesitan el contexto correcto para no caer en patrones genéricos de React o inventar props», la asimetría es difícil de explicar.

Números que se contradicen entre sí

Hay tres respuestas a «cuántos componentes hay»:

Las listo sin reconciliarlas, porque nada en las fuentes las reconcilia. El conteo de la CLI es el único que un lector puede verificar, y cuenta las partes compuestas como nombres separados — las 13 entradas Chat* importan todas de @astryxdesign/core/Chat, así que «174 componentes» se acerca más a «174 nombres exportados en 78 grupos de importación». Es una convención defendible, pero hace que 180+ parezca marketing y 150+ parezca desactualizado, quizá en ese orden.

La misma deriva aparece en la tabla de paquetes. Lista core, cli, build y los temas, y menciona aparte lab, vega y charts. Nunca menciona @astryxdesign/richtext — que está publicado (private: false, v0.7.12, HTTP 200 en el registro) — ni @astryxdesign/native. La cadena «richtext» aparece cero veces en el README, aunque el sitio de documentación tiene una entrada titulada «Introducing Astryx RichText».

Lo que sí está bien construido

Una auditoría que solo enumera huecos es tan inútil como una nota de prensa. Seis cosas aquí superan la norma de la categoría, y todas son comprobables:

El documento del guardián de IME. IME_GUARD_DESIGN.md está marcado «Scratch design doc for the reviewer. Not shipped.» Inventaría siete sitios con keydown en core, encuentra tres duplicando un predicado en línea y argumenta por qué keyCode === 229 sigue siendo «load-bearing» aunque isComposing sea la señal estándar. Ese refactor aterrizó: hoy existe packages/core/src/utils/ime.ts y al menos diez archivos importan isImeKeyEvent. Quedan dos duplicados fuera de las pruebas, y uno importa: hooks/useTypeahead.ts mantiene un isComposingKey() local que solo mira isComposing y descarta el respaldo 229, que es justo el caso que el documento decía no descartar.

Herramientas de alineación de versiones. astryx doctor ejecuta ocho comprobaciones contra un proyecto real y reporta por separado core-installed, version-alignment, themes, config e integraciones, saliendo con código 0 y severidad informativa. Los sistemas de diseño normalmente no traen ningún diagnóstico.

Cadencia de releases con etiquetas reales. 45 releases, semver de principio a fin, v0.1.1 a v0.7.11 en 135 días, más dist-tags canary por commit. El repositorio va por delante del release (package.json dice 0.7.12), que es la forma normal de un tronco activo.

Disciplina de pruebas. 1,76:1 de pruebas frente a código en core, 332 archivos de especificación de accesibilidad y un script check:repo que encadena unas treinta puertas — referencias de paleta, tablas de días CLDR, manifiestos publicados, límites entre paquetes, changesets.

Un ecosistema que ya existe. El buscador de npm devuelve 76 paquetes que coinciden con «astryx», incluidos ports no oficiales @astryx-vue/core (0.7.14 — por delante del 0.7.11 oficial), @astryx-svelte/theme-neutral y temas de terceros como @antscorp/astryx-theme-antsomi. Cuatro meses y medio después, otras personas están portando tu sistema de diseño. Es la señal de adopción más fuerte de todo este expediente, y es externa.

Una política de seguridad que dice la verdad. SECURITY.md deriva los reportes al bug bounty de Meta y afirma: «Only the latest released version of each @astryxdesign/* package receives security updates.» Sin promesa de LTS, sin teatro de backports. Quien necesite fijar versiones durante un año debería leer esa línea dos veces — con 3.212 versiones publicadas, «la última» se mueve constantemente.

Qué verificar antes de adoptarlo

Si estás evaluando Astryx para una aplicación en producción construida con agentes, estas comprobaciones son baratas y cada una cierra una pregunta que la documentación deja abierta.

# 1. ¿Sobrevive el canal del agente a TU instalación? (npx astryx no es la CLI)
npm install @astryxdesign/core
npx astryx component --list      # esperado: could not determine executable to run
npx @astryxdesign/cli component --list   # esperado: Components (174)

# 2. Después de init, corrige el bloque que escribió la herramienta
npx @astryxdesign/cli init
grep -n "npx astryx" AGENTS.md   # reemplaza por npx @astryxdesign/cli

# 3. Confirma la dependencia par que no puedes evitar
npm ls @stylexjs/stylex          # «sin librería de estilos» instala una igual

# 4. Revisa el diagnóstico antes de confiar en la capa de temas
npx @astryxdesign/cli doctor

# 5. Cuenta lo que realmente recibes
npx @astryxdesign/cli component --list --json | jq '.data.components | length'

Y cuatro preguntas para hacerle directamente a los mantenedores, porque ninguna fuente las responde:

• ¿Cuál es la evidencia de accesibilidad de los otros 164 componentes? El registro cubre 10 y se generó el 2026-02-05. Los archivos de especificación existen; el resumen no.
• ¿Debería postinstall seguir llamándose capa de cumplimiento 1 cuando npm 12 y pnpm 10 lo suprimen por defecto?
• ¿Se volvió a derivar la decisión sobre el descubrimiento después de que los pilotos 3 y 4 mostraran el suelo en 2/2 y 1/2 en lugar de 0/5?
• ¿Cuál de 150+, 180+ o 174 es el número, y qué significa «un componente» a efectos de soporte?

Fija versiones exactas. SECURITY.md solo da soporte a la última, y el registro se mueve más de veinte veces al día.

Preguntas frecuentes

¿Astryx es de verdad el sistema de diseño interno de Meta o un proyecto nuevo con ese nombre? Ambas cosas se afirman y solo una es comprobable. El README dice que «creció dentro de Meta durante los últimos ocho años… impulsando más de 13.000 aplicaciones». El repositorio público se creó el 2026-01-09, el primer release fue el 2026-06-26 y el copyright abarca varios años. Un historial de 6.948 commits con un solo autor al 49,1% (cixzhang, 3.413 commits, seguido de josephfarina 650 y vjeux 638) es compatible con un historial interno largo exportado de una vez. Las cifras de 13.000 aplicaciones y ocho años no se pueden verificar desde fuera; trátalas como contexto, no como evidencia.

¿Necesito StyleX en mi proyecto? Necesitas tenerlo instalado, no configurado. @stylexjs/stylex es una dependencia par dura de @astryxdesign/core, y npm la instala automáticamente — confirmé que node_modules/@stylexjs/stylex aparece tras instalar solo core. No necesitas un plugin de compilación de StyleX para la ruta de CSS precompilado, que es lo que significa «sin plugin de compilación» en el README. «Sin librería de estilos que adoptar» es la parte que exagera: adoptaste una, solo que no tienes que configurarla. Si prefieres la ruta de clases utilitarias, la cascada convive con Tailwind — mira Tailwind CSS en 2026 y el enfoque de componentes con IA de OpenUI para ver cómo otros sistemas manejan ese mismo límite.

¿Por qué falla npx astryx si el README lo muestra? Porque astryx en npm es un paquete 0.0.0 ajeno y sin ejecutable. El nombre solo resuelve bien cuando @astryxdesign/cli es una dependencia del proyecto. Usa npx @astryxdesign/cli, o añade el alias de script que sugiere el README ("astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs").

¿Es el servidor MCP mejor ruta que la CLI para los agentes? Para coste de instalación, sí: nada que instalar, dos herramientas, un error limpio de 123 bytes cuando falla y un manifiesto de 88.788 bytes reemplazado por un esquema de 2.178. Para profundidad, no: get() devuelve algo más por componente que la CLI (13.040 frente a 10.029 bytes), lo que cuesta contexto. La respuesta práctica es MCP para descubrir, CLI para todo lo que necesites automatizar o verificar.

¿astryx init escribe CLAUDE.md? No por defecto. El init normal escribe AGENTS.md y GEMINI.md. --agent claude apunta a CLAUDE.md o .claude/CLAUDE.md, --agent cursor prefiere .cursorrules, y --user escribe un archivo de habilidad a nivel de equipo en ~/.agents/skills/astryx/SKILL.md con enlaces a las carpetas de habilidades de cada agente. La redacción del README de core («escribe el índice de componentes en tu AGENTS.md/CLAUDE.md») describe el flag, no el comportamiento por defecto.

¿Es seguro usarlo hoy en producción? Es una beta 0.7.x que lo dice en el README, con 730 issues abiertas, sin LTS y con actualizaciones de seguridad solo para la última versión. Los componentes están muy probados y la capa CSS es una cascada de importaciones normal. Fija versiones, lee la guía de migración antes de actualizar y ejecuta astryx doctor en CI. Si tu producto depende de UI generada por agentes, reserva tiempo para verificar tú mismo la calidad del código: el arnés del propio proyecto todavía no la puntúa.

El patrón que conviene llevarse

Astryx no es un fraude. Las pruebas son reales, las especificaciones de accesibilidad son reales, el análisis de IME es el tipo de documento que escriben los ingenieros a los que ya mordió, y el experimento de descubrimiento es más riguroso que el marketing al que sostiene — detectó su propia contaminación, publicó el fallo y siguió ejecutando hasta que el efecto se encogió a nada.

Lo que falla es más estrecho y más instructivo: el rigor apunta hacia dentro. Veintiséis reglas de lint imponen convenciones a quien ya trabaja en el monorepo. Un programa de medición corre cuatro pilotos en tres semanas y deja de revisarse. Un registro de accesibilidad se detiene en 10 de 174 componentes. Y el único artefacto escrito específicamente para los de fuera — la hoja de referencia para agentes — les ordena ejecutar un comando que falla en el estado para el que fue diseñado.

Todos los sistemas de diseño afirman hoy estar listos para agentes. La pregunta útil no es si la afirmación está en el README, sino qué canal sobrevive a una instalación limpia sin ningún humano en el bucle. Para Astryx, medido por su propio arnés dentro de su propio repositorio, la respuesta honesta es: el aviso del README a veces, el servidor MCP remoto de forma fiable, y nada de lo que menciona la hoja de referencia. Es un producto mucho mejor que el eslogan, y ya está escrito en un archivo que el README no enlaza.