Astryx

项目概览

Astryx 是一套开源设计系统，最初在 Meta 内部历经八年打磨而成，目前已支撑超过 13000 个应用。它提供 150 余个无障碍组件、品牌级主题、暗黑模式、即用模板以及配套 CLI，构成一个完整的设计体系。开发者只需引入预构建的 CSS 与类型化 React 组件，无需配置构建插件，也无需额外引入样式库——人类工程师与 AI 助手可共用同一套工具进行构建。

当前版本为 Beta，基于 React 19 及更高版本与 StyleX 构建。

设计理念

• 开放内部结构：组件可在任意层级组合，底层构件均直接导出；当需要深度定制时，可通过 swizzle 将组件完整源码抽出到本地项目中。
• 无样式锁定：内部使用 StyleX 编写样式，但对使用者完全透明。可通过 className 用 Tailwind、CSS Modules 或原生 CSS 覆盖样式。
• 无需封装即可定制：主题本质上是一组 CSS 自定义属性覆盖，设计师无需分叉仓库或包裹组件源码即可让系统呈现独特品牌风格。
• 为人与 AI 共同设计：API、文档、CLI 协同设计，使人类与 AI 助手从同一参考资料、以同一种方式构建。

快速开始

Astryx 要求 React 19 及以上版本，react 与 react-dom 是 @astryxdesign/core 的 peer 依赖。

# 使用 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

最简配置只需少量 CSS 导入加上主题提供者，无需构建插件或 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 形式调用，避免路径错误。

包结构

包名	用途
@astryxdesign/core	组件、主题系统与工具方法
@astryxdesign/cli	CLI 工具：组件文档、模板、脚手架、主题、代码迁移（codemod）
@astryxdesign/build	StyleX 源码构建插件
@astryxdesign/theme-*	七套开箱即用的可定制主题：neutral、butter、chocolate、matcha、stone、gothic、y2k

@astryxdesign/lab（实验性组件）仅供内部 Storybook 与 sandbox 使用，未发布到 npm。@astryxdesign/vega 与 @astryxdesign/charts 仅以 @canary 标签发布，尚无稳定版本。

核心原则

• 引导而非强制：组件提供能力而非护栏，传入什么值就渲染什么。
• 强约定、强文档：所有组件遵循统一的命名、属性与组合规则，并配有详尽文档，便于人类与 AI 预测陌生组件的行为。
• 人与 AI 同一系统：API、约定、文档、CLI 协同演进，每一次让 AI 更易用的改进同时让人类更易用。
• 以测量为依据：约定通过测试验证而非断言，结论保留弹性，遇新场景即复审。

架构组成

• 基础层：排版、颜色、布局与无障碍，构成视觉一致与可访问界面的基石。
• 组件层：150 余个可复用 UI 构件，提供完整 TypeScript 支持。
• 模式层：经过验证的设计方案，覆盖表格页、详情页、表单向导、导航、数据录入等常见场景。

项目结构

目录	说明
apps/	示例应用、文档站点、Storybook
packages/	已发布包：core、cli、build、themes
internal/	内部工具：测试工具、eslint 插件、vibe tests

参与贡献

仓库要求 Node 22+（活跃 LTS）与 pnpm 11。推荐通过 Corepack 启用固定版本：

corepack enable
pnpm install

约定与评审标准见贡献 Wiki，包括 API 约定、设计约定、组件生命周期、贡献模板与博客评审细则。提交 PR 前请先阅读对应条目。

许可证

MIT。