astryx: A Chinese Translation of Meta's Design System, and What It Actually Takes to Run It

The Chinese translation of meta/astryx was published on 2026-11-08, the same day the original sits at 14,331 stars. The translated repository has zero stars, which is the honest starting point: this is a documentation port, not a fork, not a maintained distribution, and not a substitute for the upstream project.

What it does give you is the full README in Chinese, plus a short "中文快速上手" section at the top that the translator explicitly marks as added material rather than a translation of the original. That distinction matters more than it sounds. The upstream README is a marketing-shaped overview; it tells you what Astryx is and why Meta built it, and then points at packages/core/README.md#quick-start for the actual integration code. A Chinese reader who only reads the translated README will still not have the install snippet. The supplementary section is an attempt to close that gap.

What the original project is

Astryx is a design system from Meta, developed internally for eight years and described in its own README as the most widely used and largest design system inside the company, supporting 13,000+ applications. It ships 150+ accessible components, brand-level theming, dark mode, templates, and a CLI as one coherent system. The stack is React 19+ and StyleX. The license is MIT. The primary language of the repository is TypeScript.

It is in Beta. That word appears in the README's own header, and it has consequences you should plan around rather than discover later.

The stated differentiators are worth reading carefully, because they explain several of the setup steps that otherwise look arbitrary:

• Component internals are open. You can compose at any level, and swizzle ejects full component source into your project.
• No style lock-in. Styles are authored in StyleX but that is invisible to consumers; you override with className using Tailwind, CSS modules, or plain CSS.
• Theming is a set of CSS custom property overrides, so designers can restyle without forking or wrapping component source.
• The API, docs, and CLI are co-designed so humans and AI assistants build from the same reference in the same way.

That last point is not decoration. It explains why the CLI has a documented footgun, covered below.

Installing it, with the parts the upstream README omits

React 19 or higher is a hard requirement. react and react-dom are peer dependencies of @astryxdesign/core, so a project on React 18 cannot use this without an upgrade.

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

The CLI can also be installed globally so the astryx command resolves anywhere:

npm i -g @astryxdesign/cli

The translation adds a step the original does not spell out: pin the CLI behind a package.json script. The upstream README warns that AI assistants or new team members invoking the CLI directly can hit path errors, and the recommended workaround is a script entry.

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

Then call it as npm run astryx -- component --list. This is a small thing that saves a class of confusing failures, particularly in agent-driven workflows where the assistant guesses at binary locations.

The final wiring is a few CSS imports plus a theme provider. No build plugin, no PostCSS config, no Babel config. The translated README states this plainly but does not reproduce the code, pointing instead at packages/core/README.md#quick-start for the full guide covering Next.js, Tailwind, Vite, and CDN setups. If you are evaluating the project, that file is the one to open, not the top-level README.

Package availability is uneven, and the README says so

Three packages have non-obvious distribution status, all stated in the original:

• @astryxdesign/lab is not published to npm at all.
• @astryxdesign/vega and @astryxdesign/charts are published only under the @canary dist-tag, with no stable release.

If a dependency plan assumes npm install @astryxdesign/charts works, it does not. You need the canary tag and you accept canary semantics. The lab package is source-only, so you are pulling from the repository.

Beta status compounds this. The README says the project is currently in Beta and the translated quick-start notes that APIs may change, so production adoption needs its own risk assessment. Nothing in either document promises stability.

Where the Chinese version actually helps

The value is narrow and real: it lowers the reading barrier for developers whose English is functional but slow, particularly for the conceptual sections. The overview, the four differentiators, and the package caveats are the parts most likely to be skimmed and most likely to cause a wrong architectural decision if misread. Having them in Chinese is a genuine reduction in friction.

The supplementary quick-start is more interesting than the translation itself. It collects the environment requirements, the peer dependency constraint, the CLI script workaround, and the package availability caveats into one place. It also flags something the upstream README never mentions: npm installs from mainland China may need a mirror or accelerated download. That is an operational note, not a translation, and it is labeled as such.

The translator is explicit about the boundary. The README body is a faithful translation; the top section is added guidance; inaccuracies should go to Issues or PRs. That labeling is the right call, because a translated README that silently mixes original claims with local additions is worse than no translation.

What the translation does not solve

Several things are absent because they are absent upstream, not because the translation failed:

• Operating system support is not specified.
• Hardware requirements are not specified.
• The Node.js version required by the CLI is not given.
• No mirror source is mentioned in the original.

The translated quick-start marks each of these as "原文未说明" rather than inventing an answer. That is the correct behavior and worth noting, since a translation that fills gaps with plausible guesses is actively harmful.

The bigger gap is code. The quick-start tells you which packages to install and which script to add, but the actual provider setup and CSS imports live in packages/core/README.md, which is not translated. A Chinese-speaking developer still needs to read English for the integration step. The translation gets you to the door; it does not open it.

I have not benchmarked Astryx or run it in a production application, so treat the setup notes here as a reading of the documentation rather than field experience.

Should you use it

If your project is on React 19 and you want a component system with 150+ accessible components, CSS-variable theming, and no style lock-in, Astryx is a reasonable candidate to evaluate. The eight years and 13,000+ applications inside Meta are the strongest argument in the README, and they are a claim about internal usage, not about external production readiness.

If your project is on React 18, stop here. The peer dependency is not advisory.

If you are evaluating it and read Chinese more comfortably than English, the translated repository is a faster way through the conceptual material and the caveats. Use it alongside the original, not instead of it, and open packages/core/README.md#quick-start before you write any integration code.

Original: https://github.com/meta/astryx
Chinese version: https://github.com/yangshun2005/astryx-cn

Chinese documentation: https://github.com/yangshun2005/astryx-cn

I'm an independent enterprise AI delivery consultant — private LLM deployment, RAG, agent workflows, AIOps. If your team is stuck somewhere in that stack, my inbox is open.