How to Install Meta's Asterix Design System in React 19
A practical guide to installing Meta's Asterix CLI, themes, and components in React 19 for AI-agent-driven UI building projects.
What is Asterix and why does it matter for AI coding agents?
Asterix is a React design system open sourced by Meta, built on top of Stylex, and designed around a specific problem: AI coding agents produce inconsistent UI. Ask an agent to build a page today and you typically get raw divs, random hex colors, and a layout that works but doesn’t look like it belongs to any coherent system. Asterix fixes this by giving agents a structured way to look up components, props, and full-page templates instead of guessing. It shipped in beta in June, sits around 18,700 GitHub stars, and runs under the MIT license. Meta says it powers more than 13,000 internal apps and has been developed internally for roughly eight years, making it the largest design system inside the company.
TL;DR
- Asterix ships as a CLI-first system where the documentation website actually reads from the CLI output, not the other way around, so docs and code can’t drift apart.
- The package includes more than 150 components (the installed CLI reports 174), plus full page and block templates like dashboards, login screens, settings pages, and AI chat layouts.
- It’s built with Stylex under the hood, but you never touch Stylex directly: you import two prebuilt CSS files and style components with Tailwind, CSS modules, or plain CSS via a
classNameprop. - The
buildcommand doesn’t generate code; you describe a page in plain English and it picks the closest template and lists the blocks and components to fill it with. - A
swizzlecommand copies a single component’s full source into your project when you need complete control, similar to the shadcn pattern but opt-in per component. - Meta publishes nightly “vibe test” benchmarks comparing Asterix, Asterix+Tailwind, shadcn+Tailwind, and raw HTML, and openly admits shadcn wins more nights overall.
- It requires React 19+ and Node 22.13+, only the neutral theme is currently marked maintained, and a single demo page can ship around 600KB of JavaScript before gzip.
MindStudio, Remy, and new opportunities
On the agenda- The state of MindStudio
- Meet Remy
- The big announcement
- Live Q&A
How do you install Asterix in a new React project?
Start with a fresh React 19 app (a Vite scaffold works fine). From there, the setup has four pieces:
- Core package: install the Asterix core package that contains the components and hooks.
- A theme: install at least one theme package, with
neutralbeing the current maintained default. - Stylex: Asterix components are written in Stylex, but you don’t configure a build plugin or Babel setup yourself. You just import two prebuilt CSS files that ship with the package.
- The CLI: install
@asterix-design/cli(or the equivalent scoped package name). This is the piece that turns Asterix into an agent-friendly system rather than just another component library.
One setup quirk worth knowing: before the CLI package is installed in a project, running plain npx asterix resolves to a different, unrelated package on npm. Use the full scoped package name until the CLI is actually installed locally, otherwise you’ll hit the wrong tool entirely.
Once installed, add a theme with a command like theme add neutral, wire a few lines into your main entry file to pull in the CSS, and start your dev server. The whole process is quick, with most of the wait time coming from npm install itself rather than anything Asterix-specific.
How does the CLI connect to Claude, Cursor, or other coding agents?
This is the part that separates Asterix from a typical component library. Running asterix init asks which coding agent you use (Claude, Cursor, Codex, and others are supported) and writes a managed instruction block into that agent’s config file. For Claude specifically, that means editing the project’s CLAUDE.md file.
The injected instructions tell the agent how to behave inside an Asterix project: start every page from a template, avoid raw divs, never hard-code hex colors or pixel values, look up a component’s real props before using it, and run a doctor command to validate the output when finished.
The more interesting command is build. You describe what you want in plain English, something like “a settings page for a SaaS app,” and instead of generating code directly, the CLI picks the closest matching page template, suggests which blocks to fill it with, and lists any remaining components needed. Meta’s stated reasoning is straightforward: AI models are effectively copying patterns, so giving them a strong, consistent example to copy produces better results than asking them to invent a layout from scratch. From there, a template command copies the chosen template directly into the project.
Beyond generation, the CLI supports lookup commands that search across components, hooks, docs, templates, and themes in one ranked result set, and a command that returns a specific component’s exact props, variants, and defaults so the agent isn’t inventing APIs that don’t exist. Every command can output JSON with stable error codes, and there’s a “dense mode” aimed at reducing token usage when an agent is reading the output. A manifest command describes the entire CLI surface, which the team refers to as an OpenAPI spec for the CLI itself.
For teams that don’t want to run the CLI directly, Asterix also offers a hosted MCP server. Adding it to Claude Code with a single command gives the agent two tools, search and get, pulling from the same underlying docs. There’s also an llms.txt-style file on the Asterix site for models that read plain-text documentation summaries, and a global init user command that writes an Asterix skill file into your home directory so every new project an agent opens already has context on the system.
How do theming and component overrides work?
Theming in Asterix is just a set of CSS variables. Swapping the look of your entire app means swapping theme variables, not forking components or wrapping them in style overrides. Seven themes exist in some form (neutral, butter, chocolate, stone, gothic, and Y2K among them), plus a built-in dark mode. Right now only neutral carries an official “maintained” status, and other themes are separate install-on-demand packages. A charts package also exists but is currently only available on the canary release channel.
When a component needs changes beyond what theming and className overrides can handle, the swizzle command copies that component’s full source code into your project. From that point, you own and maintain it directly, similar to how shadcn/ui works, except you only swizzle the specific components you need to change. Everything else keeps receiving upstream updates automatically. One catch: if you swizzle a component, you need a Stylex compiler wired into your own build from that point forward, or the swizzled component won’t render correctly.
Is Asterix worth using right now?
It depends on where your project stands. Meta publishes nightly automated benchmarks (“vibe tests”) where agents build the same UI prompts four different ways: with Asterix alone, Asterix plus Tailwind, shadcn plus Tailwind, and raw HTML, with a separate judge model scoring the output. On a strong night, Asterix scored 98, shadcn scored 95, and raw HTML scored 82. On a published bad night, Asterix dropped to 77 because the agent invented imports and props that didn’t exist. Meta’s own numbers show shadcn winning the most nights across their full test history, which is a fairly transparent thing for a company to publish about its own tool.
Practically, Asterix is in active beta (version 0.7 at time of writing) with frequent releases, so expect breaking changes. It requires React 19 or newer and Node 22.13 or newer, so React 18 codebases are excluded for now. The strict “no divs, no hex values” ruleset is great for consistency but may clash with teams heavily invested in Tailwind utility-first workflows. Bundle size is also a real consideration: a single demo page came in around 600KB of JavaScript before gzip.
- Name
- Maria Alvarez
- Date of birth
- SSN
- Diagnosis
- Balance due
- $412.80
For a brand-new React 19 project where a lot of the UI will be generated by an agent, Asterix is worth trying, since the template-first, lookup-based approach visibly changes what the agent outputs from the very first page. For a mature app already built on shadcn or MUI, waiting for Asterix to exit beta, or testing it on a side project first, is the more cautious path.
Frequently Asked Questions
Does Asterix require Stylex knowledge to use?
No. Components are built with Stylex internally, but you interact with the system by importing two prebuilt CSS files and styling components through a className prop using Tailwind, CSS modules, or plain CSS. You only need a Stylex compiler in your own build if you swizzle a component.
What React and Node versions does Asterix need?
Asterix requires React 19 or newer and Node 22.13 or newer for its CLI. Projects still running React 18 aren’t currently supported.
How is Asterix different from shadcn/ui?
Both offer a “copy the source into your project” escape hatch (swizzle vs. shadcn’s add command), but Asterix layers a CLI-driven agent workflow on top: templates, a plain-English build command, prop lookups, and an MCP server meant to guide AI coding agents toward consistent output.
Can I use Asterix without running the CLI manually?
Yes. Asterix offers a hosted MCP server that gives agents like Claude Code two tools, search and get, pulling from the same documentation the CLI uses, plus an llms.txt-style file for models that read plain-text doc summaries.
Is Asterix production ready?
It’s in active beta (version 0.7 at the time of this writing) with near-daily releases. Only the neutral theme is marked maintained, and Meta’s own published benchmarks show it doesn’t always outperform shadcn. It’s reasonable for new projects and experimentation, but teams with mature production apps may want to wait for a stable release.
