Blog
Meta Asterix design systemAsterix CLIAsterix Claude Code

How to Set Up Meta's Asterix Design System With an AI Agent

Set up Meta's open-source Asterix design system with Claude Code or Cursor: the init, build, template and theme commands, the MCP server, and beta limits.

Portrait of Luis Chavez-Mattos
Edited by Luis Chavez-Mattos, Director, Product··RSS

For Engineering and Design

A person sits on top of an oversized, blank rounded UI button with their legs dangling, holding a color swatch card against its surface as if trying out a new theme.

What is Meta's Asterix design system?

Asterix is an open-source React design system from Meta, released in beta in June under the MIT license. It grew inside Meta over about eight years and powers more than 13,000 internal apps. Unlike most component libraries, it is built for coding agents as well as people. A command-line tool (the CLI) serves as the documentation, so you and your agent, such as Claude Code or Cursor, look things up in the same place and build with the same rules.

TL;DR

  • Asterix ships accessible React components such as app shell, dialogs, tables, forms and date pickers, plus full page and block templates like dashboards, login pages and settings screens.
  • The init command writes a managed block of rules into your agent's instruction file (CLAUDE.md for Claude Code), telling it to start from templates and never hard-code colors.
  • The build command takes a plain-English description and returns the closest template, suggested blocks and components, not generated code.
  • You can reach the same docs through a hosted MCP server with two tools, search and get, or through init user, which installs a skill for every project.
  • It is beta (version 0.7) and needs React 19 or newer and Node 22.13 or newer, so older apps are out for now.
  • Meta publishes nightly tests where Asterix beat Shadcn on a good night, but it also published a bad night and says Shadcn wins more nights overall.

Why do agents build inconsistent UIs in the first place?

Ask an agent for a screen and you tend to get the same result: a pile of divs, random hex colors, some Tailwind classes, and a layout that works but doesn't look like it belongs to any product. The agent has no system to follow, so it guesses.

Asterix's answer is to give the agent a real system and a way to look things up instead of inventing them. Meta's reasoning, as described in coverage of the release, is that AI is a copycat, so you hand it good examples to copy. That is why templates sit at the center of the workflow.

What do you get with Asterix?

  • Components. Accessible React components with full TypeScript types: app shell, dialogs, tables, forms, date pickers and more.
  • Page and block templates. Complete layouts you can drop into an app, such as a dashboard, login page, settings page or AI chat screen.
  • Themes. A theme is a set of CSS variables, so you can restyle the whole system without forking components. There are seven themes, including neutral, butter, chocolate, stone, gothic and Y2K. Dark mode is built in.
  • Styling with no build setup. Asterix is written with Stylex, but you never touch it. You import two pre-built CSS files. There is no build plugin, PostCSS setup or Babel config.
  • Custom styling. To change how a component looks, pass a class name from Tailwind, CSS modules or plain CSS.
  • Swizzle. This command copies a component's full source into your project so you own it. It resembles the Shadcn approach, but you only do it for components you want to change. The rest keep getting upstream fixes.

What do you need before you start?

Check these first, because they rule out a lot of existing projects:

RequirementDetail
React19 or newer
Node22.13 or newer (for the CLI)
ThemeOnly neutral is marked as maintained. Other themes are separate packages you install first
ChartsThe charts package is only on the Canary channel
Swizzled componentsYou need a Stylex compiler in your build, or that page won't render

How do you set up Asterix with Claude Code or Cursor?

These steps follow a walkthrough in a fresh Vite React app. Exact package names and flags are in the Asterix README, so check it before copying anything.

  1. Create a fresh Vite React app on React 19.
  2. Install four things: the Asterix core package, the neutral theme, Stylex and the CLI.
  3. Use the full package name for the CLI. Until the CLI is installed in your project, running plain npx asterix points to a different, unrelated package on npm. Use the full scoped package name from the README until it is installed.
  4. Run init and name your agent. Claude, Cursor, Codex and a few others are supported. It writes a managed block into that agent's instruction file (CLAUDE.md for Claude).
  5. Add a theme with theme add neutral, then wire up the roughly 15 lines in your main file that import the two CSS files and apply the theme.
  6. Start the dev server and ask your agent to build.

The whole demo took a few minutes, most of it spent waiting on npm install.

What does the init command tell your agent?

The managed block is a short rulebook. According to the walkthrough, it tells the agent to:

  • Start every page from a template.
  • Not write raw divs.
  • Not hard-code hex colors or pixel values.
  • Look up a component before using it.
  • Run the doctor command when it is done.

Because this lives in the file your agent already reads at the start of each session, you don't have to repeat the rules in every prompt.

How do the build and template commands work?

This is the part that changes what the agent produces. You describe what you want, for example "a settings page for a SaaS app." The build command does not generate code. It picks the closest page template, suggests blocks to fill it, and lists components for whatever is left.

Then the template command copies that template into your project. In the demo, the result was a full settings page with a sidebar, forms, toggles and proper spacing, without the agent improvising the layout.

A prompt you could give your agent once init has run:

Build a settings page for a SaaS app using Asterix.
Run the build command first, use the template it suggests,
look up each component's props before using it,
and run doctor when you're finished.

What other commands help the agent avoid guessing?

  • Search returns one ranked list across components, hooks, docs, templates and themes.
  • Component lookup returns a single component's exact props, types, variants and defaults, so the agent stops inventing props that don't exist.
  • JSON output with stable error codes, plus a dense mode that cuts token use.
  • Manifest describes the whole CLI in a machine-readable way, which the project compares to an open API spec for the CLI.

What if you don't want the agent running a CLI?

You have two other routes.

The hosted MCP server. MCP (Model Context Protocol) is a standard way to give an AI tool extra abilities. Add the Asterix server to Claude Code with one command and your agent gets two tools, search and get, which read from the same docs. The command is in the Asterix docs. The site also publishes an llms.txt file, a plain-text summary for AI tools.

The user skill. Install the CLI globally and run init user. It writes an Asterix skill into your home folder and links it into Claude Code and a few other agents. Every project you open then already knows Asterix, with no per-project setup.

Does Asterix actually produce better UIs?

Meta runs what it calls vibe tests, in a folder in the repo. Every night, agents get the same UI prompts and build them four ways: Asterix, Asterix plus Tailwind, Shadcn plus Tailwind, and raw HTML. A separate judge agent scores the results.

On a good night, Asterix scored 98, Shadcn 95 and raw HTML 82. Meta also published a bad night where Asterix fell to 77 because the agent made up imports and props. The project says openly that Shadcn wins the most nights across its full record. Treat these as Meta's own tests, not independent benchmarks, but the honesty about bad results makes them more useful.

What are the downsides?

  • Beta software. Version 0.7, with new releases almost every day. Expect things to change.
  • Strict agent rules. "No divs, no raw hex values" is good for consistency. If your team lives in Tailwind utility classes, you have to decide how much of the rulebook to follow.
  • Bundle size. The single demo page came to around 600 KB of JavaScript before gzip.
  • Version limits. Apps on React 18 are out for now.
  • Theme and chart gaps. Only neutral is maintained, and charts are Canary only.

What does this mean for you?

If you start a new React 19 app and build a lot of UI with agents, Asterix is worth an afternoon. Install it in a throwaway project, run init, and ask for a page. You will see quickly whether the template-first approach matches how you work.

If you have a mature app on Shadcn or MUI, wait until it leaves beta, or try it on a side project first. Migrating a live product to a daily-changing beta is a poor trade.

If you're not a developer, the idea still applies. Consistent output comes from giving an AI a defined system and examples to copy, not from better wording in a prompt. You can use the same thinking in any tool you direct an agent with.

Can you get a consistent interface without wiring up a design system yourself?

If what you need is an internal tracker, dashboard or request form rather than a front-end library to maintain, you can skip the setup. Remy builds and deploys a full-stack business app from a plain-English description, and each build includes a design system, a database, sign-in and a live URL. For example, you could describe a vendor-request form with approvals instead of juggling a spreadsheet. Remy is a separate product from Asterix. Asterix suits developers who want control over their React code, while Remy is aimed at people who want the finished app.

Frequently Asked Questions

5 questions

Is Asterix free?

Yes. It is open source under the MIT license and powers more than 13,000 internal apps at Meta. You still pay for whatever coding agent you use with it.

Do I need Tailwind or Stylex to use Asterix?

No. Asterix is written with Stylex, but you import two pre-built CSS files and never write Stylex yourself. You only need a Stylex compiler if you swizzle a component. For custom styles you can pass class names from Tailwind, CSS modules or plain CSS.

Which coding agents does Asterix support?

The init command supports Claude, Cursor, Codex and a few others, writing rules into each agent's instruction file. The hosted MCP server works with agents that support MCP, and init user links a skill into Claude Code and a few other agents.

Why does running npx asterix not work?

Before the CLI is installed in your project, plain npx asterix points to an unrelated package on npm. Use the full scoped package name from the Asterix README until the CLI is installed locally.

Is Asterix ready for production apps?

It is in beta at version 0.7 with near-daily releases, so expect changes. It has run Meta's internal apps for years, but the open-source package is newer. New projects can try it now. Established apps should probably wait.

How we source, write, and correct our articles. Editorial standards

Related articles

Straight to your inbox.
New pieces as they publish. No noise.