Astryx
Upstream: meta/astryx
at cb2558efd0bd1e8988b8bf3d47fc1252343858a9, MIT, Copyright (c) 2026
Meta Platforms, Inc. This file is a first-party rewrite in this
repository's words (MIT); no upstream text, plugin, CLI code or agent
block is vendored. Pin and notes: SOURCES.md.
Astryx is a React design system: components, design tokens, themes,
page and block templates, and a CLI, @astryxdesign/cli, that prints
their docs. This skill has no scripts/. It runs no command of its own
and uses no network; the commands below are ones you run in the product
repo.
Actors. The builder implements or reviews UI code with Astryx. The
designer and the architect consider Astryx when they choose a
component library. The operator decides the actions this file marks
as theirs. The manager receives rulings and asks.
Iron law
Get Astryx facts from the project's own CLI, at the project's version.
Never write a component name, prop, token, template or command from
memory. Read it from the CLI first.
When to load
- builder: load this skill when the turn implements or reviews UI
code in a product repo and either condition holds:
- the product's
package.json lists an @astryxdesign/* package in
dependencies, devDependencies or peerDependencies;
- the product's approved LLD or approved mockups name Astryx.
- designer or architect: load this skill when the turn chooses a
component library for a React web UI.
- Do not load it for backend, tooling, config, tests-only, docs-only or
copy-only turns, or for a UI that is not React.
- This skill is not a language skill and replaces none. builder: load
it beside the one language skill per the
load-with list,
ui-craft and
modern-web-guidance. Designer and
architect turns load no language skill.
How to read Astryx facts
Facts. The project's CLI is a devDependency, @astryxdesign/cli, at
the same version as @astryxdesign/core. Find that version in
package.json and the lockfile. The CLI documents itself; read its docs,
not the files under node_modules/@astryxdesign/.
Pick the runner from the first row that matches:
| Condition in the product repo |
Runner |
package.json has an astryx script |
The package manager's run command, such as npm run astryx -- <args> |
@astryxdesign/cli is installed as a devDependency |
The package manager's exec runner, such as pnpm exec astryx <args> or npx @astryxdesign/cli <args> |
@astryxdesign/core is installed, the CLI is not |
npx @astryxdesign/cli@<core version> <args>, for reads only |
- The package manager is the one the lockfile names, per
lang-js-ts.
- Never run the unscoped
npx astryx: upstream states that it resolves to
an unrelated npm package. Use a runner from the table.
- Adding the CLI as a devDependency is a dependency change. Follow the
language skill's dependency rules and the LLD; until then, use the
third row.
- When a command prints a follow-up command, run it with your runner.
Reads, in the order to try them:
search "<what you need>" — one ranked list across components, hooks,
docs, templates and themes, each with its follow-up command. Narrow
with --type component|hook|doc|template|theme.
component <Name> — props, variants, examples and related block
templates. component --list lists every component.
hook <name> — one hook's docs.
docs <topic> — reference docs, such as docs tokens, docs theme,
docs layout. docs alone lists the topics.
template --list; template <name> prints a template's source;
template <name> --skeleton prints its layout skeleton.
build "<idea>" — the template to start a page from and the parts it
lacks.
manifest --json — every command, option and response type of the
installed version. <command> --help gives one command.
Output options: --json gives a typed envelope on every command except
bare groups; --dense gives compact text for component and docs;
--detail brief|compact|full sets list and docs size.
Build workflow
- Read the approved stories and mockups from
ux-design, the LLD, and the nearest existing
screen. They decide what to build.
- For each new page, run
build "<idea>". Note the template it names and
the parts it lacks.
- Run
template <name> <dir>, with <dir> inside the item's scope. It
writes the template's files into that folder. Its receipt names them.
- Keep the template's frame, gap and padding. Replace only its content.
- For each part the template lacks, run
template <Block> for a block
template, then component <Name> for each component you use.
- Read a component's props with
component <Name> before you write it.
- For colors, spacing, radius and type, read
docs tokens; for theming,
docs theme. Use tokens, not literal values.
- On an existing page, keep its structure and change only what the item
asks; do not re-scaffold it.
Delivery checks
Run these before you hand off, in order:
- Re-read each file you changed.
- In lines the item adds or changes, replace each raw
<div> or <span>
that an Astryx component or layout covers with that component. Read it
with component <Name>.
- Replace each stylesheet import and each
@apply you added with a
component prop or a token. The Astryx and theme CSS imports that the
project's setup requires stay.
- In lines the item adds or changes, replace each hard-coded hex color or
px value with a token from
docs tokens.
- Run the project's build script. Hand off that build and its output, not
a description of the page. If the build fails, fix it or report the
failure.
- Run the
ui-craft pass,
unless the product's UI craft note
records option 2 or 3. Done evidence follows
verify-before-done.
What wins on conflict
Never rows of every loaded skill and
security-hardening apply
throughout; this list orders the rest. The earlier item wins; name each
conflict in your handoff.
- What is built: the approved mockups and stories (
ux-design), the
brief and the LLD. An Astryx template never adds scope: drop template
parts that the mockups and stories do not ask for.
- How it is built: Astryx components, tokens and templates, read from
the CLI.
- Visual rules where Astryx is silent:
ui-craft. Where a ui-craft
rule and an Astryx token or template disagree, the Astryx token or
template wins. If the UI craft note records option 2 or 3, skip
ui-craft.
- Platform features and code: between
modern-web-guidance and the
one language skill, such as lang-js-ts, follow
modern-web-guidance's Precedence list.
Commands that change things outside the item
Each row states what the command changes, then what you may do.
| Command |
What it changes |
Allowed action |
npm i -g @astryxdesign/cli |
Installs a CLI for the whole computer. It prints update notices and keeps computer-level agent skill files in home-folder agent folders current |
Use the project-local CLI. The operator may choose it for their own computer |
astryx init --user |
Writes ~/.agents/skills/astryx/SKILL.md and links or copies it into other agents' skill folders, such as ~/.claude/skills |
Use the project-local CLI. The operator may choose it for their own computer |
astryx init, astryx init --all, --features with agents, or astryx init --remove-agents |
Writes, or removes, a managed Astryx block in the repo's AGENTS.md and its Claude file (CLAUDE.md, else .claude/CLAUDE.md), and an import line in GEMINI.md; --remove-agents also edits other agent files. In a repo governed by this SDLC, those files are agent text |
Run astryx init --features theme,template; its theme feature writes theme.template.ts, inside the item's scope. If the product wants the agent block, make it its own reviewed item |
astryx gap-report ... --confirm-public |
Files a public GitHub issue with the user's gh login: a public post |
Ask the operator first per Asking the operator. Without --confirm-public, no public handler runs and no GitHub issue is filed; handlers that the project or its integrations configure as internal always run. You may prepare the report and put it in the ask, with every destination the output lists |
swizzle <Name>, upgrade --apply, template <name> <dir>, theme commands that add, switch or build a theme |
Edit or add project files: ejected component source, codemods, scaffolded pages, theme files. upgrade --apply also runs the hooks.postCodemod commands in astryx.config |
Run them only on files inside the item's scope |
The hosted MCP server, https://astryx.atmeta.com/mcp (tools search, get) |
Sends your query to a public remote service. Connecting it adds an MCP server to the agent's configuration |
Prefer the local CLI. Send only generic component questions; never private code, names or data. The operator may choose to connect it |
| The upstream Claude Code or Codex plugin |
A marketplace install of agent text this repo has not reviewed |
Never marketplace-install it from this skill. Load this skill instead |
Choosing Astryx at design time
designer and architect: apply this section; the build workflow
and delivery checks are the builder's. Give these facts in the list of
component-library options; this skill does not recommend Astryx for every
product.
- Fit. Astryx is a candidate when the product UI is React 19 or
later.
react and react-dom 19 or later, and @stylexjs/stylex, are
peer dependencies of @astryxdesign/core.
- What it offers. Over 150 accessible components, page and block
templates (dashboards, settings, forms, detail pages), design tokens,
dark mode and brand theming through CSS custom properties, and seven
ready-made themes. Styles are pre-built CSS imports: no build plugin.
Consumers may override with
className using Tailwind, CSS modules or
plain CSS.
- Status. Astryx is Beta. The chart packages (
@astryxdesign/vega,
@astryxdesign/charts) are published only under the @canary tag, and
@astryxdesign/lab is not published.
- Cost. Adopting it adds npm dependencies:
@astryxdesign/core, a
theme package such as @astryxdesign/theme-neutral, and
@stylexjs/stylex, plus @astryxdesign/cli as a devDependency. Follow
the product's dependency rules.
- Record. If the product chooses Astryx, the architect records
the choice and the exact version in the product's LLD. That version is
the one the builder's CLI reads at.
- Reading before a project exists. The architect reads the
current stable release with
npm view @astryxdesign/core version (the
latest tag, never @canary) and records it in the LLD. Every read
uses npx @astryxdesign/cli@<that version> <read>. The hosted MCP row
above applies to remote questions.
- License. MIT.
1---2name: astryx3description: use this when a builder implements or reviews UI code in a product whose package.json depends on an @astryxdesign/* package, or whose approved LLD or mockups name Astryx; or when a designer or architect chooses a component library for a React web UI. it says how to get Astryx facts from the project's own CLI, how to build a page from Astryx templates, which delivery checks to run, and what wins on conflict. it loads beside the one language skill, ui-craft and modern-web-guidance, not in place of them. do not use for backend-only work, non-React UIs, or products that do not use or choose Astryx.4metadata:5 source: https://skillmd.com/skills/alexderz/astryx6---78# Astryx910Upstream: [meta/astryx](https://github.com/meta/astryx/tree/cb2558efd0bd1e8988b8bf3d47fc1252343858a9)11at `cb2558efd0bd1e8988b8bf3d47fc1252343858a9`, MIT, Copyright (c) 202612Meta Platforms, Inc. This file is a first-party rewrite in this13repository's words (MIT); no upstream text, plugin, CLI code or agent14block is vendored. Pin and notes: [SOURCES.md](../../SOURCES.md).1516**Astryx** is a React design system: components, design tokens, themes,17page and block templates, and a CLI, `@astryxdesign/cli`, that prints18their docs. This skill has no `scripts/`. It runs no command of its own19and uses no network; the commands below are ones you run in the product20repo.2122**Actors.** The **builder** implements or reviews UI code with Astryx. The23**designer** and the **architect** consider Astryx when they choose a24component library. The **operator** decides the actions this file marks25as theirs. The **manager** receives rulings and asks.2627## Iron law2829**Get Astryx facts from the project's own CLI, at the project's version.**30Never write a component name, prop, token, template or command from31memory. Read it from the CLI first.3233## When to load34351. **builder:** load this skill when the turn implements or reviews UI36 code in a product repo and either condition holds:37 - the product's `package.json` lists an `@astryxdesign/*` package in38 `dependencies`, `devDependencies` or `peerDependencies`;39 - the product's approved LLD or approved mockups name Astryx.402. **designer** or **architect:** load this skill when the turn chooses a41 component library for a React web UI.423. Do not load it for backend, tooling, config, tests-only, docs-only or43 copy-only turns, or for a UI that is not React.444. This skill is not a language skill and replaces none. **builder:** load45 it beside the one language skill per the46 [load-with list](../language-router/SKILL.md#load-with-list),47 [`ui-craft`](../ui-craft/SKILL.md) and48 [`modern-web-guidance`](../modern-web-guidance/SKILL.md). Designer and49 architect turns load no language skill.5051## How to read Astryx facts5253**Facts.** The project's CLI is a devDependency, `@astryxdesign/cli`, at54the same version as `@astryxdesign/core`. Find that version in55`package.json` and the lockfile. The CLI documents itself; read its docs,56not the files under `node_modules/@astryxdesign/`.5758Pick the runner from the first row that matches:5960| Condition in the product repo | Runner |61| --- | --- |62| `package.json` has an `astryx` script | The package manager's run command, such as `npm run astryx -- <args>` |63| `@astryxdesign/cli` is installed as a devDependency | The package manager's exec runner, such as `pnpm exec astryx <args>` or `npx @astryxdesign/cli <args>` |64| `@astryxdesign/core` is installed, the CLI is not | `npx @astryxdesign/cli@<core version> <args>`, for reads only |6566- The package manager is the one the lockfile names, per67 [`lang-js-ts`](../lang-js-ts/SKILL.md#tooling--verify).68- Never run the unscoped `npx astryx`: upstream states that it resolves to69 an unrelated npm package. Use a runner from the table.70- Adding the CLI as a devDependency is a dependency change. Follow the71 language skill's dependency rules and the LLD; until then, use the72 third row.73- When a command prints a follow-up command, run it with your runner.7475Reads, in the order to try them:76771. `search "<what you need>"` — one ranked list across components, hooks,78 docs, templates and themes, each with its follow-up command. Narrow79 with `--type component|hook|doc|template|theme`.802. `component <Name>` — props, variants, examples and related block81 templates. `component --list` lists every component.823. `hook <name>` — one hook's docs.834. `docs <topic>` — reference docs, such as `docs tokens`, `docs theme`,84 `docs layout`. `docs` alone lists the topics.855. `template --list`; `template <name>` prints a template's source;86 `template <name> --skeleton` prints its layout skeleton.876. `build "<idea>"` — the template to start a page from and the parts it88 lacks.897. `manifest --json` — every command, option and response type of the90 installed version. `<command> --help` gives one command.9192Output options: `--json` gives a typed envelope on every command except93bare groups; `--dense` gives compact text for `component` and `docs`;94`--detail brief|compact|full` sets list and docs size.9596## Build workflow97981. Read the approved stories and mockups from99 [`ux-design`](../ux-design/SKILL.md), the LLD, and the nearest existing100 screen. They decide what to build.1012. For each new page, run `build "<idea>"`. Note the template it names and102 the parts it lacks.1033. Run `template <name> <dir>`, with `<dir>` inside the item's scope. It104 writes the template's files into that folder. Its receipt names them.1054. Keep the template's frame, gap and padding. Replace only its content.1065. For each part the template lacks, run `template <Block>` for a block107 template, then `component <Name>` for each component you use.1086. Read a component's props with `component <Name>` before you write it.1097. For colors, spacing, radius and type, read `docs tokens`; for theming,110 `docs theme`. Use tokens, not literal values.1118. On an existing page, keep its structure and change only what the item112 asks; do not re-scaffold it.113114## Delivery checks115116Run these before you hand off, in order:1171181. Re-read each file you changed.1192. In lines the item adds or changes, replace each raw `<div>` or `<span>`120 that an Astryx component or layout covers with that component. Read it121 with `component <Name>`.1223. Replace each stylesheet import and each `@apply` you added with a123 component prop or a token. The Astryx and theme CSS imports that the124 project's setup requires stay.1254. In lines the item adds or changes, replace each hard-coded hex color or126 px value with a token from `docs tokens`.1275. Run the project's build script. Hand off that build and its output, not128 a description of the page. If the build fails, fix it or report the129 failure.1306. Run the [`ui-craft`](../ui-craft/SKILL.md#one-verification-pass) pass,131 unless the product's [UI craft note](../ui-craft/SKILL.md#which-version-ask-once-per-product-repo)132 records option 2 or 3. Done evidence follows133 [`verify-before-done`](../verify-before-done/SKILL.md).134135## What wins on conflict136137Never rows of every loaded skill and138[`security-hardening`](../security-hardening/SKILL.md#never) apply139throughout; this list orders the rest. The earlier item wins; name each140conflict in your handoff.1411421. **What is built:** the approved mockups and stories (`ux-design`), the143 brief and the LLD. An Astryx template never adds scope: drop template144 parts that the mockups and stories do not ask for.1452. **How it is built:** Astryx components, tokens and templates, read from146 the CLI.1473. **Visual rules where Astryx is silent:** `ui-craft`. Where a `ui-craft`148 rule and an Astryx token or template disagree, the Astryx token or149 template wins. If the UI craft note records option 2 or 3, skip150 `ui-craft`.1514. **Platform features and code:** between `modern-web-guidance` and the152 one language skill, such as `lang-js-ts`, follow153 [modern-web-guidance's Precedence list](../modern-web-guidance/SKILL.md#precedence).154155## Commands that change things outside the item156157Each row states what the command changes, then what you may do.158159| Command | What it changes | Allowed action |160| --- | --- | --- |161| `npm i -g @astryxdesign/cli` | Installs a CLI for the whole computer. It prints update notices and keeps computer-level agent skill files in home-folder agent folders current | Use the project-local CLI. The operator may choose it for their own computer |162| `astryx init --user` | Writes `~/.agents/skills/astryx/SKILL.md` and links or copies it into other agents' skill folders, such as `~/.claude/skills` | Use the project-local CLI. The operator may choose it for their own computer |163| `astryx init`, `astryx init --all`, `--features` with `agents`, or `astryx init --remove-agents` | Writes, or removes, a managed Astryx block in the repo's `AGENTS.md` and its Claude file (`CLAUDE.md`, else `.claude/CLAUDE.md`), and an import line in `GEMINI.md`; `--remove-agents` also edits other agent files. In a repo governed by this SDLC, those files are agent text | Run `astryx init --features theme,template`; its theme feature writes `theme.template.ts`, inside the item's scope. If the product wants the agent block, make it its own reviewed item |164| `astryx gap-report ... --confirm-public` | Files a public GitHub issue with the user's `gh` login: a public post | Ask the operator first per [Asking the operator](../sdlc/SKILL.md#asking-the-human). Without `--confirm-public`, no public handler runs and no GitHub issue is filed; handlers that the project or its integrations configure as internal always run. You may prepare the report and put it in the ask, with every destination the output lists |165| `swizzle <Name>`, `upgrade --apply`, `template <name> <dir>`, `theme` commands that add, switch or build a theme | Edit or add project files: ejected component source, codemods, scaffolded pages, theme files. `upgrade --apply` also runs the `hooks.postCodemod` commands in `astryx.config` | Run them only on files inside the item's scope |166| The hosted MCP server, `https://astryx.atmeta.com/mcp` (tools `search`, `get`) | Sends your query to a public remote service. Connecting it adds an MCP server to the agent's configuration | Prefer the local CLI. Send only generic component questions; never private code, names or data. The operator may choose to connect it |167| The upstream Claude Code or Codex plugin | A marketplace install of agent text this repo has not reviewed | Never marketplace-install it from this skill. Load this skill instead |168169## Choosing Astryx at design time170171**designer** and **architect:** apply this section; the build workflow172and delivery checks are the builder's. Give these facts in the list of173component-library options; this skill does not recommend Astryx for every174product.1751761. **Fit.** Astryx is a candidate when the product UI is React 19 or177 later. `react` and `react-dom` 19 or later, and `@stylexjs/stylex`, are178 peer dependencies of `@astryxdesign/core`.1792. **What it offers.** Over 150 accessible components, page and block180 templates (dashboards, settings, forms, detail pages), design tokens,181 dark mode and brand theming through CSS custom properties, and seven182 ready-made themes. Styles are pre-built CSS imports: no build plugin.183 Consumers may override with `className` using Tailwind, CSS modules or184 plain CSS.1853. **Status.** Astryx is Beta. The chart packages (`@astryxdesign/vega`,186 `@astryxdesign/charts`) are published only under the `@canary` tag, and187 `@astryxdesign/lab` is not published.1884. **Cost.** Adopting it adds npm dependencies: `@astryxdesign/core`, a189 theme package such as `@astryxdesign/theme-neutral`, and190 `@stylexjs/stylex`, plus `@astryxdesign/cli` as a devDependency. Follow191 the product's dependency rules.1925. **Record.** If the product chooses Astryx, the **architect** records193 the choice and the exact version in the product's LLD. That version is194 the one the builder's CLI reads at.1956. **Reading before a project exists.** The **architect** reads the196 current stable release with `npm view @astryxdesign/core version` (the197 `latest` tag, never `@canary`) and records it in the LLD. Every read198 uses `npx @astryxdesign/cli@<that version> <read>`. The hosted MCP row199 above applies to remote questions.2007. **License.** MIT.