# Astryx: Meta's React Design System for People and Coding Agents

> Astryx is an MIT-licensed React 19 design system from Meta, shipping 150+ components, seven themes and a CLI. It targets teams that want open component internals and the same reference for humans and AI assistants.

**facebook/astryx** — Astryx is Meta's customizable React design system, with tokens and components prepared for both developers and coding agents.

- Repository: https://github.com/facebook/astryx
- Website: http://astryx.atmeta.com
- Stars: 13,496 · Forks: 1,165
- Language: TypeScript
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/facebook-astryx

## What Astryx Is and Who It Is Meant For

Astryx is a React design system published by Meta under the MIT licence. The README describes it as an open source design system that grew inside Meta over eight years, where it powered 13,000+ apps. That history explains the shape of the release: it is not a weekend component kit but a system with foundations (typography, color, layout, accessibility), 150+ components, and documented patterns for table pages, detail layouts, form wizards and data entry flows.

The intended audience is narrow in one respect and broad in another. It is narrow because Astryx requires React 19 or later; react and react-dom are peer dependencies of @astryxdesign/core, so an application pinned to React 18 cannot use it without an upgrade. It is broad because the system is explicitly built for two kinds of builder at once: engineers and the AI assistants working alongside them. The README states the API, docs and CLI were designed together so a person and an agent build the same way from the same reference, and that every change which made Astryx easier for AI made it easier for people too.

That second claim is the interesting one. Most design systems treat agent support as a documentation problem. Astryx treats it as a packaging problem, which is why there is a CLI in the same install as the components.

## The Mechanism: CSS Imports, StyleX Internals, and Swizzle

The README is specific about what consumers do and do not adopt. Astryx authors its styles with StyleX, but the README says that is invisible to consumers: you import pre-built CSS and use typed React components, with no build plugin required. The simplest setup is described as a few CSS imports plus a theme provider, with no PostCSS or Babel configuration.

That separation matters because StyleX normally implies a compile step. Here the compiled CSS is shipped, and StyleX appears in the install command as a peer dependency rather than as something you configure. The README also states that overriding is done through className, so Tailwind, CSS modules or plain CSS can sit on top without fighting the system.

Theming follows the same logic. A theme is a set of CSS custom property overrides, which means a designer can restyle Astryx without forking or wrapping component source. Seven ready-made themes are listed: neutral, butter, chocolate, matcha, stone, gothic and y2k.

For deeper changes there is swizzle, which the README describes as ejecting a component's full source into your project to own. This is the opposite of a closed top-level API. You get composable building blocks exported directly, and an escape hatch when composition is not enough. The cost is real: ejected source stops receiving upstream fixes unless you track them yourself.

## Installing Astryx and Rendering a First Component

The README gives install commands for npm, pnpm and yarn. The npm form installs the core package, one theme, and the StyleX peer dependency, then adds the CLI as a dev dependency.

```bash
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli
```

After installing, the README recommends adding a script to package.json rather than calling the binary by path. It states this avoids path errors when AI assistants or new developers invoke the CLI directly.

```json
"scripts": {
  "astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}
```

With that script in place, the README shows the component listing command as npm run astryx -- component --list. That is the first thing worth running: it prints the components available in your installed version, which is the fastest way to check that the package resolved correctly before you wire up CSS imports and a theme provider.

The README points to packages/core/README.md for the full quick start, including Next.js, Tailwind, Vite and CDN setups. It does not reproduce those steps in the top-level file, so treat the core README as the authoritative setup guide rather than the root README.

## Where Astryx Falls Short

The most concrete limitation is stated in the README itself: Astryx is currently in beta. Beta status is not a marketing hedge here, because the release history supports it. The most recent release given is v0.5.0 on 2026-08-24, and the two before it, v0.4.7 and v0.4.6, landed on 2026-08-23 and 2026-08-22. Three releases in three days at a 0.x version number tells you the API surface is still moving. The last push to the repository was on 2026-08-24, so the codebase is not dormant, but a rapid patch cadence is the opposite of a frozen interface.

The second limitation is packaging, not code. The README states that @astryxdesign/lab, the experimental components, is used internally for Storybook and the sandbox and is not published to npm. It also states that @astryxdesign/vega, the Vega/Vega-Lite chart wrapper, and @astryxdesign/charts are published only under the @canary dist-tag, with no stable release yet. If your product needs charts, Astryx does not currently offer them on a stable tag, and installing a canary build is a decision you make knowingly.

The third is the React 19 requirement. It is a hard floor, not a recommendation, and it makes Astryx the wrong tool for a codebase that cannot yet move off React 18. The fourth is subtler: the README states a principle of guidance over enforcement, meaning components render whatever value you pass. That is a deliberate trade. You get capability instead of guardrails, and you also get less protection from your own inconsistent props.

## Astryx Compared with Copy-in Component Collections

The obvious alternative for a React team is a copy-in component collection such as shadcn/ui, where you generate component source into your repository and own it from day one. The difference in approach is fundamental rather than cosmetic.

With a copy-in collection, the initial cost is low and the long-term cost is maintenance: you own every component you generate, and upstream improvements arrive as diffs you must apply by hand. Astryx inverts that. You depend on @astryxdesign/core as a versioned package, receive fixes through normal dependency updates, and only eject source when you specifically choose to swizzle a component. The README frames this as open internals: components are built to be composed at any level, with building blocks exported directly, and swizzle reserved for the cases where you need to go deeper.

The trade is that you inherit Astryx's release cadence. During beta, that cadence is fast. A copy-in collection insulates you from upstream churn because the code is already yours; a package dependency does not. Teams that cannot absorb 0.x breaking changes on their own schedule should weigh that honestly, because swizzling every component to escape it defeats the purpose of installing the package.

## Maintenance, Licence and Upgrade Cost

The repository is not archived, and the last push was on 2026-08-24. The release history shows v0.5.0 on that same date, with v0.4.7 and v0.4.6 in the two days before. The project is therefore moving, but the version number is the thing to plan around: at 0.x, semver permits breaking changes in minor releases, so a jump from 0.4 to 0.5 can require code edits.

The repository layout suggests the project takes its own upgrade mechanics seriously. There is a .changeset directory, which indicates changesets are used to record version bumps, and a check:changesets script in the root package.json that validates them. The CLI package is described in the README as covering component docs, templates, scaffolding, themes and codemods. Codemods are the relevant part for upgrades: they are the mechanism by which a design system can move consumer code automatically rather than through release notes.

On licensing, the repository and its root package.json both declare MIT, and the README links a LICENSE file. MIT is permissive, but the practical question for a design system is not the licence text; it is whether the theme packages and any assets you ship carry the same terms. The README lists seven theme packages under packages/themes without separate licence notes. That is worth confirming against the individual package manifests before you redistribute anything, and it is a question for your own legal review rather than something this article can settle.

## Conclusion

Adopt Astryx if you are on React 19 or later, want an MIT-licensed component set whose internals you can swizzle, and are willing to accept beta status and a StyleX peer dependency. Do not adopt it if you need charts on a stable tag, since @astryxdesign/charts and @astryxdesign/vega are published only under @canary, or if you cannot move to React 19. Before committing, verify the component list with npm run astryx -- component --list, confirm the theme packages you need are published, and read packages/core/README.md for the Next.js, Vite, Tailwind and CDN setup paths.

## FAQ

### What is Astryx by Meta?

Astryx is Meta's open source React design system, released under the MIT licence. The README describes it as having grown inside Meta over eight years, where it powered 13,000+ apps, and it ships 150+ accessible components, theming, dark mode, templates and a CLI as one system.

### How do you use Astryx?

Install @astryxdesign/core with a theme package and the StyleX peer dependency, then add @astryxdesign/cli as a dev dependency. The README says the simplest setup is a few CSS imports plus a theme provider, with no build plugin, PostCSS or Babel config, and points to packages/core/README.md for the full guide.

### What does Astryx mean?

The README does not give a meaning or etymology for the name. It only states that Astryx is an open source design system built on React 19+ and StyleX.

### What is astryx?

Astryx is an open source design system from Meta, currently in beta, built on React 19+ and StyleX. It ships 150+ accessible components, brand-level theming, dark mode, templates and a CLI, and the README says it powers 13,000+ apps inside Meta.

## Sources

- [Official documentation](http://astryx.atmeta.com)
- [Official README](https://github.com/facebook/astryx#readme)
- [Project repository](https://github.com/facebook/astryx)
- [Release notes](https://github.com/facebook/astryx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/facebook-astryx