astryx README

The project's README from github.com/facebook/astryx. As one markdown file: README.md.

Astryx

Astryx

An open source design system that's fully customizable and built for how we build now:
by people and the agents working alongside them.

Currently in Beta · Built on React 19+ and StyleX

npm version license MIT PRs welcome

Docs Storybook Sandbox

Docs · Storybook · Sandbox · Contributing · Discord

Overview

Astryx is an open source design system that grew inside Meta over the last eight years, where it became the most-used and largest design system in the company — powering 13,000+ apps and shaped by the engineers, designers, and product teams who depend on it every day.

It ships 150+ accessible components, brand-level theming, dark mode, ready-to-ship templates, and a CLI as one cohesive system. You import pre-built CSS and use typed React components — no build plugin, no styling library to adopt — and both people and AI assistants build with the same tooling.

What makes Astryx different:

Getting Started

Astryx requires React 19 or later (react and react-dom are peer dependencies of @astryxdesign/core).

Install Astryx, a theme, and its peer dependencies:

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

# pnpm
pnpm add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
pnpm add -D @astryxdesign/cli

# yarn
yarn add @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
yarn add -D @astryxdesign/cli

The simplest setup is a few CSS imports plus a theme provider — no build plugin, no PostCSS or Babel config. See the @astryxdesign/core README for the full guide (Next.js, Tailwind, Vite, and CDN).

For reliable CLI access, add a script to your package.json:

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

Then use it as npm run astryx -- component --list. This avoids path errors when AI assistants or new developers invoke the CLI directly.

Packages

Package Description README
@astryxdesign/core Components, theme system, and utilities README
@astryxdesign/cli CLI tooling: component docs, templates, scaffolding, themes, and codemods README
@astryxdesign/build Build plugins for StyleX source builds README
@astryxdesign/theme-* Seven ready-made, fully customizable themes (neutral, butter, chocolate, matcha, stone, gothic, y2k) README

@astryxdesign/lab (experimental components) is used internally for Storybook and the sandbox and is not published to npm. @astryxdesign/vega (Vega/Vega-Lite chart wrapper) and @astryxdesign/charts (chart components) are published to npm only under the @canary dist-tag — there is no stable release yet.

Principles

These are the promises Astryx makes to the people building on it.

Architecture

Foundations

The building blocks for visually cohesive and accessible interfaces: typography, color, layout, and accessibility.

Components

A library of 150+ reusable UI building blocks with full TypeScript support.

Patterns

Battle-tested design solutions for common interactions and workflows: table pages, detail page layouts, form wizards, navigation patterns, data entry flows.

Project Structure

Directory Purpose
apps/ Example apps, the docsite, and Storybook
packages/ Published packages: core, cli, build, themes
internal/ Internal tooling: test utilities, eslint plugin, vibe tests

Contributing

We welcome contributions! See CONTRIBUTING.md for the full guide.

Questions, or want a hand with a PR? Come find us in Discord.

Our conventions and review rubrics live in the Contributing wiki — including API Conventions, Design Conventions, the Component Lifecycle, and the Contributing Templates and Blog Review rubrics. Read the relevant one before opening a PR.

Quick start for contributors: this repo uses Node 22+ on an active LTS line and pnpm 11. Install pnpm directly, or enable Corepack once so the pinned pnpm version installs automatically:

corepack enable
pnpm install

If corepack is missing, install pnpm directly or install Corepack manually; see the troubleshooting notes in CONTRIBUTING.md.

License

MIT

astryx (facebook/astryx)

Searching Database…

13.7K ·GitHub
Astryx
What is this?Astryx is an open source, agent-ready design system built inside Meta over eight years, offering 150+ accessible React components, brand theming, dark mode, ready-made templates, and a CLI as one cohesive system.
Is this a framework or a component library?It is a React component library (design system) distributed as npm packages, not a framework — you import pre-built CSS and typed React components directly, without adopting a build plugin or separate styling library.
How do I add Astryx to a project?Install @astryxdesign/core, a theme package (e.g. @astryxdesign/theme-neutral), and peer dependencies, then add a few CSS imports plus a theme provider — no build plugin, PostCSS, or Babel config is required.
What do I need before installing it?You need React 19 or later, since react and react-dom are required peer dependencies of @astryxdesign/core; contributing to the monorepo itself requires Node 22+ and pnpm 11.
Is everything in Astryx production-ready?The core system is in Beta, and the chart packages (@astryxdesign/vega, @astryxdesign/charts) are published to npm only under the @canary tag with no stable release yet; @astryxdesign/lab is internal-only and not published at all.
Who is this built for?It's aimed at teams building React 19 web apps who want a component system that both human developers and AI coding assistants can use the same way, following the same API and docs.
What makes Astryx different from a typical closed design system?Its components are 'open internals' — building blocks are exported directly for composition, and a swizzle CLI command can eject a component's full source into your project so you fully own and edit it.
Does Astryx lock me into a specific styling approach?No — Astryx authors its own styles with StyleX internally, but that's invisible to consumers; you can override components with className using Tailwind, CSS modules, or plain CSS.
How do I customize the look without forking components?A theme in Astryx is just a set of CSS custom property overrides, so you can restyle the whole system without wrapping or forking component source.
Which themes ship out of the box?Seven ready-made, fully customizable themes are included: neutral, butter, chocolate, matcha, stone, gothic, and y2k.
What are similar projects?arc-library, chakra-ui, shoelace, base-ui, react-native-ui-kitten, kumo, boardui, react-spectrum
Which topics is it in?design-tools, templates, ui-library, dark-mode, design-system, playwright, theme, accessibility, monorepo, vite, component-library, nextjs
Creator
facebook
Size
1.1 GB
Stars
13.7K
Updated
CommitOct 17Releasev0.7.1Oct 15
Age
9mo
Commits · 90 Days