共计 4945 个字符,预计需要花费 13 分钟才能阅读完成。

下面这张仪表盘,是我在自己的 Linux 测试机上搭出来的。折线图、四张指标卡、底下的分布条,都是 Astryx 自带的页面模板;我自己手写的只有两个文件,加起来 34 行,干的事就是把主题接上,再放两个按钮切主题、切深浅色。

Astryx 是 Meta 刚放到 GitHub 上的设计系统,说白了就是一整套现成的 React 界面零件:按钮、表格、对话框、导航栏,外加配色主题和一个命令行工具。README 里说它在 Meta 内部用了 8 年,撑着 13,000 多个应用。今天早上 GitHub 日榜它排第一,一天涨了 3,111 颗星,总数 22,718(北京时间 11 月 11 日 7:57 读数)。

它要解决的问题挺朴素。自己写个后台、小工具,或者让 AI 帮你生成一个页面,功能能跑,长得却像 2008 年的论坛。Astryx 给的是一套风格统一的零件,深色模式和无障碍都带着;另外还给 AI 编码助手备了一份说明书,省得 AI 自己瞎拼样式。
目前它还标着 Beta,我装的是 11 月 11 日凌晨 5 点多(北京时间)刚发的 v0.7.13。截至 11 月 16 日 GitHub 最新为 v0.7.16,本文基于 v0.7.13。下面按我实际敲命令的顺序写,每一步后面附上我看到的结果。
动手前,你需要准备什么
- Node.js 22.13 或更新。这个数是
astryx doctor自己报的下限,我用的是 v24.22.1。 - 一个 React 19 的项目。没有的话,第 1 步现建一个。
- 能正常访问 npm 的网络。
我用的是 Vite,因为它最轻。官方 README 里 Next.js、Tailwind、甚至不打包直接走 CDN 的写法都有,这篇没测那几种。
第 1 步:建一个空项目
npm create vite@latest demo -- --template react-ts --no-interactive
cd demo
npm install
--no-interactive 是为了不让它一路问问题。我这边建项目 0.7 秒,npm install 7 秒。做完你会得到一个能跑的 Vite + React + TypeScript 空壳。
第 2 步:装 Astryx 本体、主题和命令行工具
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli
三个包分别是:组件本体、一套叫 neutral 的主题、样式引擎 StyleX。最后那个是命令行工具。
装完 npm 11 会打出一段 warn,说 @astryxdesign/core 和 @astryxdesign/cli 的 postinstall 脚本没执行。我翻了这两个脚本的源码,它们只做一件事:提醒你去跑 init。没跑不影响使用,第 3 步手动跑就行,不用去批准脚本。
还有个容易搞混的地方,core 的 README 特意提醒:命令行要用带前缀的包名,也就是 npx @astryxdesign/cli ...。在 CLI 还没装进项目时,直接 npx astryx 会去找 npm 上另一个同名的、跟 Meta 无关的包。像我这样已经 -D 装进项目了,npx astryx 才会调到项目里那份。
第 3 步:让命令行工具先自我介绍
npx astryx component --list
npx astryx component Button --zh
第一条列出全部组件,我这边显示 Components (174),比 README 写的「150+」还多一些。第二条打印 Button 的完整用法,--zh 是中文。

中文目前是半成品:Props 表的说明大多翻好了,「Best Practices」和「Accessibility」两段还是英文,个别属性的说明也还是英文。不过查个属性叫什么、默认值是多少,已经够用了。
再跑一次初始化:
npx astryx init
它会在项目根目录写出 AGENTS.md(我这里 2214 字节)和 GEMINI.md,后者只有一行,指回 AGENTS.md。这就是前面说的给 AI 看的说明书,里面写了组件数量、必须引入的样式文件、做页面要「先从模板起步」这些规矩。不少 AI 编码助手打开项目时会先读这类文件,比如 Codex 读 AGENTS.md。core 的 README 说项目里有 CLAUDE.md 时也会写进去,我这个空项目里没有,所以只看到这两个。我这次没接 AI 助手去验证它到底多听话,这一点先按官方的说法记下。

第 4 步:接上主题
这一步不做,组件会以「没穿衣服」的样子出来。先让 doctor 体检一下:
npx astryx doctor
我这里 Node 版本、包版本对齐都是 ok,只有一项 warn:主题包装了,但没接到应用里。按它给的提示:
npx astryx theme add neutral
它会生成 src/astryx-themes.ts,文件头写着 do not edit manually,别手改它。然后把 src/main.tsx 换成下面这样,两个 CSS 的引入顺序别颠倒:
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import '@astryxdesign/core/reset.css'
import '@astryxdesign/core/astryx.css'
import App from './App.tsx'
createRoot(document.getElementById('root')!).render(
<StrictMode>
<App />
</StrictMode>,
)
我顺手把 Vite 自带的 index.css 引入删了,免得它的默认样式跟 Astryx 打架。
第 5 步:拿一个现成页面模板
不想从零拼页面的话,可以直接问它:
npx astryx build "dashboard"
它会推荐用 dashboard 模板,同时列出另外几个候选,比如带告警栏的、带计分卡的。模板总共有多少?我用 template --list --json 数了一下,779 个,其中整页模板 58 个,其余 721 个是可以拼进页面的区块。
把模板写进项目:
npx astryx template dashboard ./src/pages/dashboard
它会写出一个 803 行的 page.tsx,并在最后一行提示还缺两个依赖。我第一遍偏不装,直接 npm run build,想看看会怎样:

三条 TS2307: Cannot find module,找不到 recharts 和 @heroicons/react。模板只复制代码,不替你装依赖,提示里那行命令照抄就好:
npm install recharts@"^3.10.1" @heroicons/react@"^2.2.0"
npm run build
再 build 就过了,整个过程 1.4 秒。产物里 CSS 300 KB(gzip 后 46 KB),JS 1.05 MB(gzip 后 323 KB),Vite 会顺带提醒单个文件超过 500 KB。图表库和整份组件样式表都打进去了,做个人工具或内部后台问题不大;要是做对加载速度很敏感的公开页面,得再按 Vite 的提示拆分代码。
第 6 步:加两个按钮,切主题、切深浅色
为了看主题到底能换多少样子,我又装了一套 matcha 主题:
npm install @astryxdesign/theme-matcha
npx astryx theme add matcha
src/App.tsx 写成这样,Theme 组件的 mode 参数管深浅色:
import { useState } from 'react'
import { Theme } from '@astryxdesign/core/theme'
import { Button } from '@astryxdesign/core/Button'
import { HStack } from '@astryxdesign/core/Layout'
import { themes, type ThemeSlug } from './astryx-themes'
import DashboardTemplate from './pages/dashboard/page'
const q = new URLSearchParams(location.search)
export default function App() {
const [slug, setSlug] = useState<ThemeSlug>((q.get('theme') as ThemeSlug) || 'neutral')
const [mode, setMode] = useState<'light' | 'dark'>(q.get('mode') === 'dark' ? 'dark' : 'light')
return (
<Theme theme={themes[slug]} mode={mode}>
<HStack gap={2} padding={3}>
<Button label={`主题:${slug}`} onClick={() => setSlug(s => (s === 'neutral' ? 'matcha' : 'neutral'))} />
<Button label={mode === 'light' ? '切到深色' : '切到浅色'} variant="primary"
onClick={() => setMode(m => (m === 'light' ? 'dark' : 'light'))} />
</HStack>
<DashboardTemplate />
</Theme>
)
}
读网址参数那两行是我为了截图方便加的,你可以删掉。npm run build 之后 npx vite preview 打开本地预览,点一下「切到深色」:

整页一起变深,图表网格线、卡片边框都跟着换,不用另写一行深色样式。再点左边的按钮换成 matcha:

标题换成了手写体,卡片圆角更大,主按钮变成深橄榄绿。页面代码一个字没改,只是换了主题。我那两个中文按钮在两套主题下都显示正常。
两个顺手要知道的小事
字体走的是 Google Fonts。 构建完再跑 npx astryx doctor --built dist,会多一条 warn,说 neutral 主题的 Figtree 字体是外部引入的,没法确认能不能加载到。打开 node_modules/@astryxdesign/theme-neutral/fonts.css,第 3 行就是 @import Google Fonts。读者网络访问不了 Google 的话,浏览器会改用后备字体,字形会跟截图不一样。我没在断网环境专门测过,介意的话可以把字体文件下载下来自己托管。
它还在 Beta,版本走得很快。 按北京时间算,11 月 7 日到 11 日这几天,GitHub 上就发了 v0.7.11、v0.7.12、v0.7.13 三个版本。升级时官方给了 npx astryx upgrade --apply 来跑迁移脚本,我这次没用上。core 和 cli 两个包的版本要对齐,doctor 会帮你查。

谁适合现在就试
如果你在写个人后台、内部工具,或者经常让 AI 帮你生成页面又嫌丑,Astryx 值得建个空项目试一下,模板加主题这条路确实省事。如果你的项目已经用惯了 shadcn/ui 或别的组件库,或者不想跟着 Beta 版本隔几天升一次,眼下没必要搬家,它也说了样式可以用 Tailwind、CSS Modules 覆盖,可以先挑一两个页面混着用。

想让 AI 编码助手更守规矩,还可以看看我之前写的 Matt Pocock 的 skills 安装和使用教程,思路跟 Astryx 的 AGENTS.md 有点像,都是先把规矩写给 AI 看。
参考来源:GitHub:meta/astryx · @astryxdesign/core README · Astryx 官网文档 · GitHub Releases · GitHub Trending
如果觉得自己操作比较麻烦,也可以联系科技喵仔获取成品。




