Astryx：Meta 的开源设计系统
本文目录
一个完全可定制的开源设计系统，为我们如今的构建方式而打造：由人以及与之并肩工作的智能体共同构建。
目前处于 Beta 阶段 · 基于 React 19+ 与 StyleX
文档 · Storybook · 沙盒 · 贡献指南 · Discord
概述#
Astryx 是一个开源设计系统，过去八年在 Meta 内部成长，成为公司内使用最广泛、规模最大的设计系统——支撑 13,000+ 个应用，并由每天依赖它的工程师、设计师和产品团队共同塑造。
它以一个连贯的系统提供 150+ 个无障碍组件、品牌级主题（brand-level theming）、暗色模式、开箱即用的模板以及 CLI。你导入预构建的 CSS 并使用带类型的 React 组件——无需构建插件，也无需引入样式库——人和 AI 助手使用同一套工具构建。
Astryx 的与众不同之处：
- 开放的内部实现。 组件可在任意层级组合，而不是被锁在封闭的顶层 API 之后。你会用到的构建块直接导出；需要更深层定制时，
swizzle可把组件完整源码弹出到你的项目中归你所有。 - 不被样式方案锁定。 Astryx 使用 StyleX 编写样式，但这对使用者不可见。可以用 Tailwind、CSS modules 或普通 CSS 通过
className覆盖——你的项目已经在用什么就用什么。 - 无需包装即可定制。 主题是一组 CSS 自定义属性（CSS custom property）覆盖，因此设计师无需 fork 或包装组件源码，就能让 Astryx 带上鲜明自己的风格。
- 为人与智能体而构建。 API、文档和 CLI 是一起设计的，因此人和 AI 助手能以相同方式、依据同一份参考进行构建。
快速开始#
Astryx 需要 React 19 或更高版本（react 和 react-dom 是 @astryxdesign/core 的 peer dependencies）。
安装 Astryx、一个主题及其 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你也可以为整台电脑安装一次 CLI，这样 astryx 可在任意文件夹中使用，且每个编码智能体都能了解 Astryx；在具体项目中，它仍会运行该项目自己的版本：
npm i -g @astryxdesign/cli项目安装、全局安装，还是两者都装？astryx docs global/project-global-or-both 会比较它们（推荐两者都装），astryx docs global 说明全局模式如何工作。
最简单的设置只需几个 CSS 导入加一个主题提供者（theme provider）——无需构建插件，也无需 PostCSS 或 Babel 配置。完整指南（Next.js、Tailwind、Vite 和 CDN）见 @astryxdesign/core 的 README。
为了可靠地使用 CLI，在 package.json 中添加脚本：
"scripts": {
"astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
}然后以 npm run astryx -- component --list 的方式使用。这样可避免 AI 助手或新开发者直接调用 CLI 时出现路径错误。
软件包#
| 软件包 | 描述 | README |
|---|---|---|
@astryxdesign/core | 组件、主题系统与工具 | README |
@astryxdesign/cli | CLI 工具：组件文档、模板、脚手架、主题与 codemods | README |
@astryxdesign/build | 用于 StyleX 源码构建的构建插件 | README |
@astryxdesign/theme-* | 七个现成、完全可定制的主题（neutral、butter、chocolate、matcha、stone、gothic、y2k） | README |
@astryxdesign/lab（实验性组件）在内部用于 Storybook 和沙盒，不发布到 npm。@astryxdesign/vega（Vega/Vega-Lite 图表包装器）和 @astryxdesign/charts（图表组件）只在 @canary dist-tag 下发布到 npm——尚无稳定版本。
原则#
这些是 Astryx 对在其之上构建的人的承诺。
- 引导而非强制。 组件给你能力，而不是与你作对的护栏。设计观点存在于文档和示例中——你传什么值，组件就渲染什么。
- 强大且有文档的约定。 每个组件都遵循相同的命名、prop 和组合规则，且每一个都有详尽文档——因此学会几个之后，其余组件就会显得熟悉，人和 AI 都能预测不熟悉的组件会如何表现。
- 人与 AI 共用一套系统。 API、约定、文档和 CLI 一起设计，因此人和 AI 助手以相同方式构建。每一项让 Astryx 对 AI 更容易的改动，也让它对人类更容易。
- 以度量赢得。 我们测试约定而不是断言约定，对结果保持开放，并在新情况证明其错误时重新审视。
架构#
基础#
构建视觉统一且无障碍界面的模块：排版、颜色、布局和无障碍。
组件#
150+ 个可复用 UI 构建块的库，提供完整 TypeScript 支持。
模式#
针对常见交互与工作流的久经考验的设计方案：表格页、详情页布局、表单向导、导航模式、数据录入流程。
项目结构#
| 目录 | 用途 |
|---|---|
apps/ | 示例应用、文档站点和 Storybook |
packages/ | 已发布包：core、cli、build、themes |
internal/ | 内部工具：测试工具、eslint 插件、vibe 测试 |
贡献#
我们欢迎贡献！完整指南见 CONTRIBUTING.md。
有问题，或需要 PR 方面的帮助？来 Discord 找我们。
我们的约定和审查标准位于贡献 wiki——包括 API Conventions、Design Conventions、Component Lifecycle、Contributing Templates 和 Blog Review Rubric。在提交 PR 之前，请阅读相关标准。
贡献者快速开始：本仓库使用活跃 LTS 线上的 Node 22+ 和 pnpm 11。直接安装 pnpm，或启用一次 Corepack，让锁定的 pnpm 版本自动安装：
corepack enable
pnpm install如果缺少 corepack，请直接安装 pnpm，或手动安装 Corepack；参见 CONTRIBUTING.md 中的故障排除说明。
Theme Showcase 的 DOM 测试使用根 ui 项目进行共享的 DOM 和 StyleX 测试设置。在仓库根目录运行 pnpm exec vitest run --project ui apps/docsite/src/__tests__/theme-showcase/。
许可证#
MIT
关于#
一个完全可定制、为智能体准备就绪的开源设计系统。
astryx.atmeta.com