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.
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 --listreturns 174 entries (some are subcomponents such asAvatarGroupOverflow), fromButtonandTabletoAppShell,SideNav,AlertDialogandStatusDot. - 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,gothicandy2k, 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
classNameusing Tailwind, CSS Modules or plain CSS. Atailwind-theme.cssbridge maps tokens to classes (bg-surface,text-primary,rounded-lg). - Swizzle:
astryx swizzle Buttonejects the component source into your project so you own it, shadcn/ui style.
Published npm packages:
| Package | Purpose |
|---|---|
| `@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:
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 diagnosticsAll 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:
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 neutralinit --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:
@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';Create a client provider with the theme and the Next link:
'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:
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:
pnpm add recharts@"^3.10.1" @heroicons/react@"^2.2.0"
pnpm exec astryx template dashboard --type page src/app/orders
pnpm buildInstalling 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.
| Without Astryx | With Astryx | |
|---|---|---|
| Time | 50 s | 85 s |
| Cost | 0.15 USD | 0.42 USD |
| Agent turns | 8 | 31 |
| Files | 3 (page, component, 260-line CSS Module) | 1 (147 lines, no custom CSS) |
| `pnpm build` | Passes | Passes |
| Dark mode | Broken (see below) | Correct |
| Table on mobile | Turns into cards | Horizontal scroll; the button sits off-screen |
| Row button | Accessible name includes the order number | Truncated 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, pickedStatusDotoverBadgebecause the rules reserveBadgefor counts, and ranastryx doctor --builtbefore finishing. It skipped the templateastryx buildsuggested (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 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
| Item | Cost |
|---|---|
| Library, CLI and the 7 themes | 0 USD (MIT) |
| Claude Code and Codex plugin | 0 USD |
| `neutral` theme fonts (Figtree) | 0 USD, loaded from Google Fonts |
| Hosting | Same as your app: Next.js renders static pages |
| Agent tokens in our test | 0.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 itsswizzlemirrors 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
Help us grow
codigoagente is free, with no paywalls. If this article helped you, any of these keeps the blog going.
- Share it with someone who'll find it usefulWhatsAppLinkedInXFacebook
- Meet our sponsorSafe Build Labs
More on Open source tools

- Free alternatives to paid apps
- Design, image and video

- Free alternatives to paid apps
- Run it on your server

- Claude Code
- Free alternatives to paid apps