Astryx 按 Meta 的设计系统搭 React 界面

Astryx 是 Meta 开源的 React 设计系统（meta/astryx，MIT 许可，目前是 Beta 版）。它在 Meta 内部用了八年，支撑过一万三千多个应用，提供 150 多个无障碍组件、七套主题、深色模式和页面模板。它为 Agent 准备了两个入口：托管的 MCP 服务器（只读查文档）和 @astryxdesign/cli 命令行（查文档、生成模板、改主题、升级）。这个 Skill 让你写界面前先查它的规范，而不是凭记忆编组件和属性。

触发

• 用户要做 React 界面、后台页面、表单、表格、弹窗、仪表盘，并且项目里已经有 @astryxdesign/core，或者用户点名要用 Astryx。
• 用户问 Astryx 某个组件怎么用、有哪些属性、怎么换主题或深色模式。
• 用户要把旧版本 Astryx 升级到新版本。

项目用的是别的组件库（shadcn/ui、MUI、Ant Design 等）而用户没提 Astryx 时，不要触发，也不要主动建议迁移。

硬性规则

• 先查后写：每个组件的名字、属性和用法都要先用 MCP 的 search / get 或 CLI 的 astryx search / astryx component <Name> 查到再写，不凭印象编属性。
• 不要运行不带作用域的 npx astryx：npm 上的 astryx 是一个无关的包。没装过 CLI 时只能用 npx @astryxdesign/cli …。
• 看 isReady：查询结果里标为未就绪的组件只能从 @canary 安装，用之前要告诉用户这是预发布版本。
• 不擅自改项目配置：astryx init、astryx theme add、astryx upgrade 和 astryx swizzle 都会写文件，先告诉用户会改哪些文件，得到同意再运行。
• 按错误码处理：用 --json 时根据返回的 code（如 ERR_UNKNOWN_COMPONENT）决定下一步，不去解析报错文字；有 suggestions 就按建议的名字重查。
• 前提条件：项目需要 React 19 以上；CLI 需要 Node.js 22.13 以上。不满足就说明原因，不要强行安装。

安装（先检查再安装）

两种接法任选一种，都接上也可以：只想查文档用 MCP，要在项目里生成代码、改主题就要用 CLI。

1. MCP（只读，不用装任何东西）

先检查 Agent 的 MCP 列表里有没有指向 https://astryx.atmeta.com/mcp 的服务器，没有再加。Claude Code：

claude mcp list
claude mcp add --transport http astryx https://astryx.atmeta.com/mcp

其他支持远程 MCP（Streamable HTTP）的 Agent，把这个地址加成一个 HTTP 服务器即可。它提供两个工具：

工具	参数	用途
search	query，可选 limit（默认 8）	用自然语言找组件、文档主题和页面模板，返回简要结果、是否就绪和安装命令
get	name，可选 section	取某个组件、Hook、文档主题或模板的完整文档：属性、用法、示例代码；大主题（如 theme）传 section 只取一节

2. CLI（查文档 + 改项目）

node -v                                   # 需要 22.13 以上
npm ls @astryxdesign/cli 2>/dev/null       # 项目里装了没有
astryx --version 2>/dev/null               # 电脑上装了没有

都没有时，经用户同意后选一种：

npm install -D @astryxdesign/cli           # 装进当前项目（版本跟着项目走）
npm i -g @astryxdesign/cli                 # 装到电脑上，任何文件夹都能用

官方建议两种都装：在项目里时，全局命令也会自动使用项目自己的版本。新项目还要装组件库和一个主题：

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

可选：astryx init --user 会在 ~/.agents/skills/astryx/SKILL.md 写一份 Astryx 自己的说明，并链接到 ~/.claude/skills 等目录，让电脑上的其他 Agent 也知道它；astryx init --user --remove-agents 可以撤掉。这一步会写用户主目录，先问用户。

按需求选命令

想做什么	MCP	CLI
不确定该用哪个组件	search { query: "带排序的表格" }	astryx search "table with sorting"
看组件的属性和示例	get { name: "Button" }	astryx component Button
列出所有组件	search 用宽泛的词	astryx component --list
看 Hook 用法	get { name: "useToast" }	astryx hook useToast
设计规范（间距、颜色、布局）	get { name: "tokens" }、get { name: "layout" }	astryx docs tokens、astryx docs layout
从模板起一个页面	search { query: "dashboard template" } 后 get	astryx template --list，astryx build "<需求>"
换主题、深色模式	get { name: "theme", section: "…" }	astryx theme add <slug>（写文件，先问）
版本升级	不支持	astryx upgrade（会改代码，先问，改完让用户看 diff）
项目体检	不支持	astryx doctor
组件不够用，要改源码	不支持	astryx swizzle <Component>（把源码拷进项目，先问）

CLI 小技巧：

• 加 --json 拿到带类型的结果，适合 Agent 解析；astryx manifest --json 一次列出所有命令和参数。
• --detail compact 只要名字和一句说明，节省上下文；--zh 读中文文档（有翻译的部分）。
• 项目里推荐用包管理器调用：pnpm exec astryx … 或 npm run astryx -- …（需要在 package.json 里加一个 astryx 脚本，见项目 README）。

工作流程

1. 确认触发条件和前提（React 19、Node 22.13）。
2. 用 search 找到候选组件或模板，再用 get / astryx component 读完整文档。
3. 按文档写代码：从 @astryxdesign/core 导入组件，引入主题的 CSS；样式覆盖用项目已有的方式（className 配 Tailwind、CSS Modules 或普通 CSS 都可以），不要引入新的样式库。
4. 需要写文件的命令（init、theme、upgrade、swizzle）先说明再执行。
5. 写完后如果项目装了 CLI，运行 astryx doctor 检查。

输出格式

• 先用一两句话说明用了哪些 Astryx 组件或模板，各自查自哪条文档。
• 然后给代码，并标出需要安装的包（未就绪的组件注明来自 @canary）。
• 最后列出改动过的文件和用户还需要做的事（例如引入主题 CSS、确认 React 版本）。