~/codigoagente
Open source tools

Astryx: Meta's open source design system built for AI coding agents (tested in Next.js)

Astryx is Meta's design system, released as open source under the MIT license: 150+ accessible React components, seven themes, dark mode, hundreds of page and block templates, and a CLI (astryx) built so an AI coding agent such as Claude Code or Codex looks things up instead of guessing props. According to its README, it grew inside Meta over eight years into the company's most-used design system, powering more than 13,000 internal apps.

We installed it in a clean Next.js 16 project, ran one of its templates without touching a line, and then asked Claude Code for the same order panel twice, with and without Astryx. Here is what works, what doesn't, and what it costs.

The "dashboard" template right after the CLI copied it, unchanged · codigoagente

What Astryx is and what it ships

We reviewed commit dec8633 on main (November 12, 2026) and version 0.7.14 on npm. The project calls itself beta.

  • MIT license (Copyright (c) 2026 Meta Platforms, Inc.): free for commercial and client work, as long as you keep the copyright notice.
  • Components: the README says "150+"; astryx component --list returns 174 entries (some are subcomponents such as AvatarGroupOverflow), from Button and Table to AppShell, SideNav, AlertDialog and StatusDot.
  • Templates: the CLI lists 58 page templates (dashboard, login, checkout, AI chat, settings, canvas editor...) and 722 blocks to fill them.
  • Themes: neutral, butter, chocolate, matcha, stone, gothic and y2k, each its own npm package (@astryxdesign/theme-*). A theme is a set of CSS custom properties, so you restyle without touching components.
  • Stack: React 19 or later is a hard requirement. Styles are authored with StyleX (Meta's CSS-in-JS library) but shipped precompiled: you import three stylesheets and need no Babel or PostCSS plugin.
  • No styling lock-in: override with className using Tailwind, CSS Modules or plain CSS. A tailwind-theme.css bridge maps tokens to classes (bg-surface, text-primary, rounded-lg).
  • Swizzle: astryx swizzle Button ejects the component source into your project so you own it, shadcn/ui style.

Published npm packages:

PackagePurpose
`@astryxdesign/core`Components, theme system and utilities
`@astryxdesign/cli`Terminal docs, templates, themes, codemods and diagnostics
`@astryxdesign/build`Plugins to build from StyleX source
`@astryxdesign/theme-*`The seven themes

The interesting part: a CLI designed for AI agents

What sets Astryx apart is that the docs live in the terminal and are written for a model to read. astryx init adds a block to your AGENTS.md or CLAUDE.md with rules like these:

  • start every page from a template (astryx build "<idea>" tells you which one);
  • read astryx component <Name> before using a component;
  • no bare <div>s, hex colors or pixel values: components and tokens (var(--color-*), var(--spacing-*));
  • run astryx doctor --built <dir> before delivering.

The commands you will use most:

terminalsh
pnpm exec astryx search "table with filters"     # search components, templates and docs
pnpm exec astryx build "order panel"              # recommended template and missing blocks
pnpm exec astryx template dashboard src/app/panel # copy the template into your project
pnpm exec astryx component Table                  # props, variants and examples
pnpm exec astryx doctor                           # project diagnostics

All of them take --json (typed output for agents) and --dense (shorter output to save tokens). The repo also ships a Claude Code and Codex plugin (plugins/astryx) with a skill that tells the agent Astryx is available and to start with astryx search. New to skills? Read what Claude Code skills are and how to install them.

Install Astryx in Next.js 16, step by step

We started from create-next-app (Next.js 16.4.6, React 19.3.0) without Tailwind:

terminalsh
pnpm create next-app@latest my-app --ts --app --src-dir --no-tailwind --eslint --use-pnpm --yes
cd my-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 writes the rules to .claude/CLAUDE.md (without --agent it writes AGENTS.md and GEMINI.md). theme add neutral generates src/astryx-themes.ts, which imports the theme and its fonts.

Replace src/app/globals.css with the base styles, in this order:

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

Create a client provider with the theme and the Next link:

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>
  );
}

And wrap the layout:

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

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

For the screenshot above we copied the dashboard template (803 lines, with Recharts charts) and built:

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

Installing took under 4 seconds, pnpm build finished in 10 seconds with no errors, and the page logged no console errors on desktop, mobile (390 px, no horizontal scroll) or dark mode, which follows the OS with zero setup.

The test: Claude Code with and without Astryx

We gave headless Claude Code (claude -p --model sonnet) the same prompt in two fresh Next.js 16 projects: one with Astryx initialized, one bare. The prompt (in Spanish) asked for an order panel for a coffee shop in Quito with four stats, a table of the last 8 orders and a button to mark each order delivered, mobile-friendly. The Astryx run was allowed to call pnpm exec astryx.

Same prompt, two results at 375 px · codigoagente
Without AstryxWith Astryx
Time50 s85 s
Cost0.15 USD0.42 USD
Agent turns831
Files3 (page, component, 260-line CSS Module)1 (147 lines, no custom CSS)
`pnpm build`PassesPasses
Dark modeBroken (see below)Correct
Table on mobileTurns into cardsHorizontal scroll; the button sits off-screen
Row buttonAccessible name includes the order numberTruncated label: "Marcar como entreg…"

What Playwright showed afterwards:

  • With Astryx the agent took the rules seriously: it read the component docs, wrote zero <div>s, picked StatusDot over Badge because the rules reserve Badge for counts, and ran astryx doctor --built before finishing. It skipped the template astryx build suggested (shell-top-nav) because it needs the StyleX compiler, and composed the page from components instead.
  • Without Astryx the result looks flashier (coffee-shop colors, cards on mobile), but it is hand-written CSS you will maintain, and every new screen will get its own style.
  • Both share one bug: after clicking "mark as delivered", the button disappears and keyboard focus drops to <body>. It is the same bug we found testing the senior-frontend skill; no design system fixes it for you.

Dark mode, the difference you don't notice at first

The same panel with the OS in dark mode · codigoagente

The version without Astryx kept the Next starter's globals.css, which turns the body black in dark mode while the panel stays cream. With Astryx, colors come from theme tokens and dark mode works without anyone asking. That is the kind of detail a design system solves once for every screen.

What Astryx costs

ItemCost
Library, CLI and the 7 themes0 USD (MIT)
Claude Code and Codex plugin0 USD
`neutral` theme fonts (Figtree)0 USD, loaded from Google Fonts
HostingSame as your app: Next.js renders static pages
Agent tokens in our test0.42 USD with Astryx vs 0.15 USD without (Sonnet)

The real cost is tokens: the agent queries the CLI a lot (31 turns vs 8), so one screen costs about three times more. In exchange you don't generate hundreds of lines of custom CSS per screen, which pays off as the app grows. If you pay per token, use --dense on CLI reads and start from templates to cut turns.

Free alternatives it competes with:

  • shadcn/ui (MIT): you copy each component's code into your project and style it with Tailwind. It is what this blog uses. Astryx has a migration guide (astryx docs migration) and its swizzle mirrors that "you own the code" model.
  • Hand-built components by the agent: free in licenses, but every screen comes out different and costs more to maintain.

For a solo developer or small agency building internal panels (orders, inventory, bookings), Astryx is the cheapest option to maintain if you are already on React 19. For a landing page with a strong custom brand, your own CSS or shadcn/ui is still more direct.

Common errors

npx astryx installs something else. The unscoped astryx npm package is unrelated to Meta. Always use npx @astryxdesign/cli <command>, or pnpm exec astryx once the CLI is a project dependency. It is a real supply-chain risk if you let an agent run it unchecked.

Components render unstyled. You are missing reset.css and astryx.css, or the order is wrong: reset first, then astryx.css, then the theme.

astryx doctor warns about theme-fonts. The neutral theme imports Figtree from fonts.googleapis.com. It is just a warning; if you don't want your site calling Google (privacy, GDPR), self-host the font.

A template doesn't compile. Some templates use StyleX directly and need the build plugin (@astryxdesign/build). astryx build tells you; if you don't want to set up StyleX, pick another template or compose the page from components.

Missing template dependencies. dashboard needs recharts and @heroicons/react. astryx build prints the exact install command.

React 18. Astryx requires React 19 or later. Upgrade first on a React 18 project.

FAQ

Is Astryx free for commercial use?

Yes. It is MIT: use it in client projects and paid products. Just keep Meta's copyright notice in distributed code.

Does Astryx replace shadcn/ui?

They cover the same ground differently. shadcn/ui copies components into your repo and relies on Tailwind; Astryx installs as a package, ships complete themes and an agent CLI, and lets you eject a component's source only when you need to (swizzle). You can use Tailwind on top of Astryx.

Does it work with Tailwind?

Yes. Its Next.js + Tailwind guide declares CSS layers in a specific order and imports tailwind-theme.css so classes like bg-surface or text-primary map to theme tokens.

Do I need Claude Code to use it?

No. It is a regular React library. The CLI and the CLAUDE.md block help an agent use it better, but you can read the same docs with astryx component <Name> or on the official site.

Is it production-ready?

The project itself says beta (0.7.x) and ships releases almost daily: eight between November 3 and 11, 2026 (0.7.7 to 0.7.14). Pin the version in package.json and run astryx upgrade --from <version> --apply when you update; it runs the codemods.

Conclusion

Astryx doesn't make Claude Code a better designer by magic: in our test, the result without it looked flashier, cost less and took less time. What it does is make the agent build with consistent, accessible, dark-mode-ready parts, without generating CSS nobody maintains. If you build panels and internal tools on React 19, install it in a scratch project, run astryx build with your idea and compare.

Next step: pair it with the senior-frontend skill so the agent tests the UI in a browser, or with Impeccable if you want a more polished design.

// source code

Repository in this article
The code this article covers is public: browse it, star it or clone it from here.

Help us grow

codigoagente is free, with no paywalls. If this article helped you, any of these keeps the blog going.

// newsletter

One email a week with the repos worth your time

The week's new articles, tested against real code. No spam; unsubscribe in one click.

ArtCraft is an open source app for AI images and video where you build the 2D or 3D scene first. Features, real costs and how to use it with your fal key.
  • Free alternatives to paid apps
  • Design, image and video
read article
PeakCut cuts long videos and YouTube, Twitch or Kick streams into 9:16 clips with word-by-word captions. Install guide, real costs and a Spanish-language test.
  • Free alternatives to paid apps
  • Run it on your server
read article
Slopus is a GPL-3.0 desktop app that plans, generates and edits images, video and music on your GPU. Agent, local generators and timeline, no FFmpeg bundled.
  • Claude Code
  • Free alternatives to paid apps
read article