~/codigoagente

Astryx: el design system open source de Meta pensado para Claude Code (lo probamos en Next.js)

Astryx es el design system de Meta publicado como open source con licencia MIT: más de 150 componentes de React accesibles, siete temas, modo oscuro, cientos de plantillas de páginas y bloques, y una CLI (astryx) diseñada para que un agente de IA como Claude Code o Codex consulte la documentación en lugar de inventarse props. Según su README, creció durante ocho años dentro de Meta hasta ser el sistema de diseño más usado de la empresa, con más de 13.000 aplicaciones internas.

Lo instalamos en un proyecto Next.js 16 limpio, levantamos una de sus plantillas sin tocar una línea y después le pedimos a Claude Code el mismo panel de pedidos dos veces, con Astryx y sin él. Te contamos qué sale bien, qué no y lo que cuesta.

La plantilla «dashboard» recién copiada con la CLI, sin cambios · codigoagente

Qué es Astryx y qué trae

Analizamos el commit dec8633 de main (12 de noviembre de 2026) y la versión 0.7.14 publicada en npm. El proyecto se declara en beta.

  • Licencia MIT (Copyright (c) 2026 Meta Platforms, Inc.): puedes usarlo en proyectos comerciales y de clientes sin pagar nada, conservando el aviso de copyright.
  • Componentes: el README habla de "150+"; astryx component --list devuelve 174 entradas (algunas son subcomponentes, como AvatarGroupOverflow). Hay desde Button y Table hasta AppShell, SideNav, AlertDialog o StatusDot.
  • Plantillas: la CLI lista 58 plantillas de página (dashboard, login, checkout, chat de IA, ajustes, editor de lienzo...) y 722 bloques para rellenarlas.
  • Temas: neutral, butter, chocolate, matcha, stone, gothic e y2k, cada uno como paquete npm aparte (@astryxdesign/theme-*). Un tema es un conjunto de variables CSS, así que se personaliza sin tocar los componentes.
  • Stack: React 19 o superior como dependencia obligatoria. Los estilos están escritos con StyleX (la librería CSS-in-JS de Meta), pero se distribuyen ya compilados: importas tres hojas CSS y no necesitas plugin de Babel ni de PostCSS.
  • Sin bloqueo de estilos: puedes sobrescribir con className usando Tailwind, CSS Modules o CSS plano. Incluye un puente tailwind-theme.css que convierte los tokens en clases (bg-surface, text-primary, rounded-lg).
  • Swizzle: astryx swizzle Button copia el código fuente del componente a tu proyecto para que lo modifiques, al estilo de shadcn/ui.

Paquetes que publica en npm:

PaquetePara qué sirve
`@astryxdesign/core`Componentes, sistema de temas y utilidades
`@astryxdesign/cli`Documentación por terminal, plantillas, temas, codemods y diagnóstico
`@astryxdesign/build`Plugins para compilar desde el código fuente con StyleX
`@astryxdesign/theme-*`Los siete temas

La parte interesante: una CLI pensada para agentes de IA

Lo que separa a Astryx de otros design systems es que la documentación vive en la terminal y está escrita para que la lea un modelo. astryx init añade un bloque a tu AGENTS.md o CLAUDE.md con estas reglas, entre otras:

  • empezar cada página desde una plantilla (astryx build "<idea>" te dice cuál);
  • leer astryx component <Nombre> antes de usar un componente;
  • no usar <div> sueltos, colores hexadecimales ni píxeles: componentes y tokens (var(--color-*), var(--spacing-*));
  • pasar astryx doctor --built <carpeta> antes de entregar.

Las órdenes que más vas a usar:

terminalsh
pnpm exec astryx search "tabla con filtros"      # busca componentes, plantillas y docs
pnpm exec astryx build "panel de pedidos"         # plantilla recomendada y bloques que faltan
pnpm exec astryx template dashboard src/app/panel # copia la plantilla a tu proyecto
pnpm exec astryx component Table                  # props, variantes y ejemplos
pnpm exec astryx doctor                           # diagnóstico del proyecto

Todas aceptan --json (salida tipada para agentes) y --dense (versión más corta para ahorrar tokens). El repositorio también trae un plugin para Claude Code y Codex (plugins/astryx) con una skill que le dice al agente que Astryx está disponible y que empiece por astryx search. Si no sabes qué es una skill, mira qué son las skills de Claude Code y cómo instalarlas.

Instalar Astryx en Next.js 16 paso a paso

Partimos de create-next-app (Next.js 16.4.6, React 19.3.0) sin Tailwind:

terminalsh
pnpm create next-app@latest mi-app --ts --app --src-dir --no-tailwind --eslint --use-pnpm --yes
cd mi-app
pnpm add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
pnpm add -D @astryxdesign/cli
pnpm exec astryx init --agent claude
pnpm exec astryx theme add neutral

init --agent claude escribe las reglas en .claude/CLAUDE.md (sin --agent las escribe en AGENTS.md y GEMINI.md). theme add neutral genera src/astryx-themes.ts, que importa el tema y sus fuentes.

Sustituye src/app/globals.css por los estilos base, en este orden:

src/app/globals.csscss
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';

Crea un proveedor de cliente con el tema y el enlace de Next:

src/app/providers.tsxtsx
'use client';

import Link from 'next/link';
import {Theme} from '@astryxdesign/core/theme';
import {LinkProvider} from '@astryxdesign/core/Link';
import {themes, defaultThemeSlug} from '../astryx-themes';

export function Providers({children}: {children: React.ReactNode}) {
  return (
    <Theme theme={themes[defaultThemeSlug]}>
      <LinkProvider component={Link}>{children}</LinkProvider>
    </Theme>
  );
}

Y envuelve el layout:

src/app/layout.tsxtsx
import './globals.css';
import {Providers} from './providers';

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="es">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Para la captura de arriba copiamos la plantilla dashboard (803 líneas, con gráficos de Recharts) y compilamos:

terminalsh
pnpm add recharts@"^3.10.1" @heroicons/react@"^2.2.0"
pnpm exec astryx template dashboard --type page src/app/pedidos
pnpm build

La instalación tardó menos de 4 segundos, pnpm build compiló en 10 segundos sin errores y la página no dio ningún error de consola en escritorio, móvil (390 px, sin scroll horizontal) ni modo oscuro, que sigue al sistema operativo sin configurar nada.

La prueba: Claude Code con y sin Astryx

Le dimos a Claude Code en modo headless (claude -p --model sonnet) el mismo prompt en dos proyectos Next.js 16 recién creados: uno con Astryx inicializado y otro sin nada. El prompt pedía un panel de pedidos para una cafetería de Quito con cuatro indicadores, una tabla de los últimos 8 pedidos y un botón para marcar cada pedido como entregado, todo en español y que se viera bien en el móvil. Al de Astryx le permitimos ejecutar pnpm exec astryx.

Mismo prompt, dos resultados a 375 px · codigoagente
Sin AstryxCon Astryx
Tiempo50 s85 s
Coste0,15 USD0,42 USD
Turnos del agente831
Archivos3 (página, componente, CSS Module de 260 líneas)1 (147 líneas, sin CSS propio)
`pnpm build`CompilaCompila
Modo oscuroRoto (ver abajo)Correcto
Tabla en el móvilSe convierte en tarjetasScroll horizontal; el botón queda fuera de pantalla
Botón de cada filaNombre accesible con el número de pedidoTexto cortado: «Marcar como entreg…»

Lo que vimos con Playwright después:

  • Con Astryx el agente se tomó en serio las reglas: leyó la documentación de los componentes, no escribió ni un <div>, usó StatusDot en lugar de Badge porque las reglas reservan el Badge para contadores, y ejecutó astryx doctor --built antes de terminar. Descartó la plantilla que le propuso astryx build (shell-top-nav) porque necesitaba el compilador de StyleX y montó la página con componentes sueltos.
  • Sin Astryx el resultado es más vistoso (colores de cafetería, tarjetas en el móvil) pero es CSS escrito a mano que tendrás que mantener, y cada pantalla nueva tendrá su propio estilo.
  • Las dos fallan igual en algo: tras pulsar «Marcar como entregado», el botón desaparece y el foco del teclado cae en <body>. Es el mismo fallo que vimos al probar la skill senior-frontend; ningún design system lo arregla por ti.

El modo oscuro, la diferencia que no se ve a primera vista

Mismo panel con el sistema en modo oscuro · codigoagente

La versión sin Astryx dejó el globals.css de la plantilla de Next, que pone el body en negro cuando el sistema está en modo oscuro, mientras el panel sigue en crema. Con Astryx los colores salen de los tokens del tema y el modo oscuro funciona sin que nadie lo pida. Es el tipo de detalle que un design system resuelve una vez para todas las pantallas.

Cuánto cuesta usar Astryx

ConceptoCoste
Librería, CLI y los 7 temas0 USD (MIT)
Plugin para Claude Code y Codex0 USD
Fuentes del tema `neutral` (Figtree)0 USD, se cargan desde Google Fonts
HostingEl mismo que tu app: genera páginas estáticas en Next.js
Tokens del agente en nuestra prueba0,42 USD con Astryx frente a 0,15 USD sin él (Sonnet)

El coste real está en los tokens: el agente consulta la CLI muchas veces (31 turnos frente a 8), así que una pantalla cuesta unas tres veces más. A cambio, no generas cientos de líneas de CSS propio por pantalla, y eso se nota cuando la aplicación crece. Si pagas por tokens, usa --dense en las consultas de la CLI y empieza desde plantillas para recortar turnos.

Alternativas gratuitas con las que se compara:

  • shadcn/ui (MIT): copias el código de cada componente a tu proyecto y lo estilas con Tailwind. Es lo que usa este blog. Astryx tiene guía de migración (astryx docs migration) y su swizzle imita ese modelo de "el código es tuyo".
  • Componentes a mano con el agente: gratis en licencias, pero cada pantalla sale con un estilo distinto y cuesta más mantenerla.

Para una persona sola o una agencia pequeña que hace paneles internos (pedidos, inventario, citas), Astryx es la opción más barata de mantener si ya usas React 19. Para una landing page con diseño de marca muy propio, CSS propio o shadcn/ui siguen siendo más directos.

Errores frecuentes

npx astryx instala otra cosa. El nombre astryx sin ámbito en npm es un paquete que no tiene nada que ver con Meta. Usa siempre npx @astryxdesign/cli <orden>, o pnpm exec astryx cuando el CLI ya está instalado en el proyecto. Es un riesgo real de cadena de suministro si se lo dejas a un agente sin revisar.

Los componentes salen sin estilos. Te falta importar reset.css y astryx.css o el orden no es el correcto: primero el reset, después astryx.css y luego el tema.

astryx doctor avisa de theme-fonts. El tema neutral importa Figtree desde fonts.googleapis.com. Es solo un aviso; si no quieres llamar a Google desde tu web (por privacidad o por el RGPD), sirve la fuente tú mismo.

Una plantilla no compila. Algunas plantillas usan StyleX directamente y necesitan el plugin de compilación (@astryxdesign/build). astryx build lo indica; si no quieres configurar StyleX, elige otra plantilla o compón la página con componentes.

Faltan dependencias de la plantilla. dashboard necesita recharts y @heroicons/react. La salida de astryx build muestra el comando exacto para instalarlas.

React 18. Astryx exige React 19 o superior. En un proyecto con React 18 tendrás que actualizar antes.

Preguntas frecuentes

¿Astryx es gratis para uso comercial?

Sí. La licencia es MIT: puedes usarlo en proyectos de clientes y en productos de pago. Solo tienes que mantener el aviso de copyright de Meta en el código distribuido.

¿Astryx sustituye a shadcn/ui?

Cubren lo mismo con enfoques distintos. shadcn/ui copia componentes a tu repositorio y depende de Tailwind; Astryx se instala como paquete, trae temas completos y una CLI para agentes, y te deja copiar el código de un componente solo cuando lo necesitas (swizzle). Puedes usar Tailwind encima de Astryx.

¿Funciona con Tailwind?

Sí. Su guía de Next.js + Tailwind declara las capas CSS en un orden concreto e importa tailwind-theme.css para tener clases como bg-surface o text-primary mapeadas a los tokens del tema.

¿Necesito Claude Code para usarlo?

No. Es una librería de React normal. La CLI y el bloque en CLAUDE.md hacen que un agente la use mejor, pero puedes leer la misma documentación tú con astryx component <Nombre> o en el sitio oficial.

¿Está listo para producción?

El propio proyecto dice que está en beta (versión 0.7.x) y publica versiones casi a diario: entre el 3 y el 11 de noviembre de 2026 salieron ocho (de la 0.7.7 a la 0.7.14). Fija la versión en package.json y usa astryx upgrade --from <versión> --apply cuando actualices, que ejecuta los codemods.

Conclusión

Astryx no hace que Claude Code diseñe mejor por arte de magia: en nuestra prueba el resultado sin él era más llamativo, salió más barato y llevó menos tiempo. Lo que sí consigue es que el agente construya con piezas consistentes, accesibles y con modo oscuro, sin generar CSS que luego nadie mantiene. Si haces paneles y herramientas internas con React 19, instálalo en un proyecto de prueba, ejecuta astryx build con tu idea y compara.

Siguiente paso: combínalo con la skill senior-frontend para que el agente pruebe la interfaz en el navegador, o con Impeccable si buscas un diseño más trabajado.

// código fuente

Repositorio del artículo
El código del que habla este artículo es público: revísalo, dale una estrella o clónalo desde aquí.

Nos ayuda a crecer

codigoagente es gratis y sin muros de pago. Si este artículo te sirvió, cualquiera de estas cosas mantiene el blog en marcha.

// newsletter

Un correo a la semana con los repos que valen la pena

Los artículos nuevos de la semana, probados con código real. Sin spam; te das de baja con un clic.

ArtCraft, app open source para crear imágenes y vídeos con IA montando antes la escena en 2D y 3D. Qué hace, cuánto cuesta y cómo usarla con tu clave de fal.
  • Alternativas gratis a apps de pago
  • Diseño, imagen y vídeo
leer artículo
PeakCut recorta vídeos largos y directos de YouTube, Twitch o Kick en clips 9:16 con subtítulos palabra a palabra. Instalación, coste real y prueba en español.
  • Alternativas gratis a apps de pago
  • Instálalo en tu servidor
leer artículo
Slopus es una app de escritorio GPL-3.0 que planifica, genera y edita imágenes, vídeo y música en tu GPU. Agente, generadores locales y timeline sin FFmpeg.
  • Claude Code
  • Alternativas gratis a apps de pago
leer artículo