Astryx Builds React UIs on Meta's Design System

Astryx is an open-source React design system from Meta (meta/astryx, MIT license, currently in Beta). It has been used inside Meta for eight years, supports over 13,000 applications, and provides more than 150 accessible components, seven themes, dark mode, and page templates. It offers two entry points for agents: the hosted MCP server (read-only documentation lookup) and the @astryxdesign/cli command line (documentation lookup, template generation, theme changes, upgrades). This skill makes you check its conventions before writing an interface, rather than inventing components and props from memory.

Triggers

• The user wants to build a React interface, admin page, form, table, dialog, or dashboard, and the project already has @astryxdesign/core, or the user names Astryx.
• The user asks how to use a specific Astryx component, what props it has, or how to change the theme or dark mode.
• The user wants to upgrade an older version of Astryx to a newer one.

When the project uses another component library (shadcn/ui, MUI, Ant Design, etc.) and the user has not mentioned Astryx, do not trigger, and do not proactively suggest migrating.

Hard Rules

• Look up before writing: Look up each component's name, props, and usage with the MCP search / get or the CLI astryx search / astryx component <Name> before writing code. Do not invent props from memory.
• Never run the unscoped npx astryx: The astryx package on npm is an unrelated package. If the CLI is not installed, use only npx @astryxdesign/cli ….
• Check isReady: Components marked as not ready in query results can only be installed from @canary. Before using them, tell the user this is a pre-release version.
• Do not change project configuration without permission: astryx init, astryx theme add, astryx upgrade, and astryx swizzle all write files. Tell the user which files will be changed, and get consent before running them.
• Handle errors by code: When using --json, decide the next step based on the returned code (such as ERR_UNKNOWN_COMPONENT) rather than parsing error text. If suggestions are present, re-query using the suggested names.
• Prerequisites: The project needs React 19 or later; the CLI needs Node.js 22.13 or later. If these are not met, explain why and do not force an installation.

Installation (check first, then install)

Choose either approach, or connect both: use MCP if you only want to look up documentation; use the CLI if you need to generate code or change themes in the project.

1. MCP (read-only, nothing to install)

First check whether the agent's MCP list already has a server pointing to https://astryx.atmeta.com/mcp; add it only if it does not. For Claude Code:

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

For other agents that support remote MCP (Streamable HTTP), add this address as an HTTP server. It provides two tools:

Tool	Parameters	Purpose
search	query, optional limit (default 8)	Find components, documentation topics, and page templates using natural language; returns brief results, readiness status, and install commands
get	name, optional section	Get full documentation for a component, Hook, documentation topic, or template: props, usage, example code; for large topics (such as theme), pass section to get only one section

2. CLI (documentation lookup + project changes)

node -v                                   # Needs 22.13 or later
npm ls @astryxdesign/cli 2>/dev/null       # Whether it is installed in the project
astryx --version 2>/dev/null               # Whether it is installed on the computer

If neither is present, after user consent choose one:

npm install -D @astryxdesign/cli           # Install into the current project (version follows the project)
npm i -g @astryxdesign/cli                 # Install on the computer, usable in any folder

The official recommendation is to install both: inside a project, the global command automatically uses the project's own version. New projects also need the component library and one theme:

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

Optional: astryx init --user writes an Astryx instruction file to ~/.agents/skills/astryx/SKILL.md and links it into directories such as ~/.claude/skills, so other agents on the computer also know about it; astryx init --user --remove-agents removes it. This step writes to the user's home directory, so ask the user first.

Choosing a Command by Need

What you want to do	MCP	CLI
Not sure which component to use	search { query: "table with sorting" }	astryx search "table with sorting"
See a component's props and examples	get { name: "Button" }	astryx component Button
List all components	search with a broad term	astryx component --list
See Hook usage	get { name: "useToast" }	astryx hook useToast
Design conventions (spacing, colors, layout)	get { name: "tokens" }, get { name: "layout" }	astryx docs tokens, astryx docs layout
Start a page from a template	search { query: "dashboard template" } then get	astryx template --list, astryx build "<requirement>"
Change theme or dark mode	get { name: "theme", section: "…" }	astryx theme add <slug> (writes files, ask first)
Version upgrade	Not supported	astryx upgrade (changes code, ask first, let the user review the diff afterward)
Project health check	Not supported	astryx doctor
Component is not enough, need to change source	Not supported	astryx swizzle <Component> (copies source into the project, ask first)

CLI tips:

• Add --json to get typed results suited to agent parsing; astryx manifest --json lists all commands and parameters at once.
• --detail compact gives only names and one-line descriptions, saving context; --zh reads the Chinese documentation (for the parts that have been translated).
• Inside a project, it is recommended to invoke via the package manager: pnpm exec astryx … or npm run astryx -- … (requires adding an astryx script in package.json; see the project README).

Workflow

1. Confirm the trigger conditions and prerequisites (React 19, Node 22.13).
2. Use search to find candidate components or templates, then use get / astryx component to read the full documentation.
3. Write code according to the documentation: import components from @astryxdesign/core and include the theme's CSS; for style overrides, use the project's existing approach (className with Tailwind, CSS Modules, or plain CSS are all fine); do not introduce a new styling library.
4. For commands that write files (init, theme, upgrade, swizzle), explain first and then run.
5. After writing, if the project has the CLI installed, run astryx doctor to check.

Output Format

• Start with one or two sentences saying which Astryx components or templates were used, and which documentation entry each came from.
• Then give the code, and list the packages to install (note components not yet ready as coming from @canary).
• Finally, list the changed files and what the user still needs to do (for example, importing the theme CSS, confirming the React version).