orbyn-astryx · git:20261108.949d5f5 · 2026-11-08 · sha256 6d18dc895d5b719c
orbyn-astryx git:20261108.949d5f5A
Immutable. This exact content never changes and is served at /api/v1/blob/6d18dc895d5b719c.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_ubb5fmemy5rwywvw/6d18dc895d5b719c357c28e410328247dcc2a98729c1f671257900454da73fb8.json
Then /plugin install orbyn-astryx@markdownregistry-ubb5fmemy5rwywvw in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: orbyn-astryx
description: "Build, theme and review React UI with Meta's Astryx design system (@astryxdesign): pages from its templates, its components and tokens, a house style as an Astryx theme. Versions change only via Dependabot, never by hand. Use when a project uses or adopts Astryx."
---
# Astryx
Follow the consuming project's instructions and requested scope; use the
[portable defaults](../orbyn-workflow/references/project-policy.md) only where guidance is missing.
Astryx is Meta's MIT-licensed design system: React 19 or later, styles authored with
StyleX and shipped as prebuilt CSS, themes as CSS custom properties, page templates,
150+ components and a CLI that prints its own documentation. [UI design](../orbyn-ui-design/SKILL.md)
still owns the product decisions; this skill owns how they are built in Astryx.
## Before you start
1. **Confirm it fits.** A project uses Astryx when its `package.json` lists an
`@astryxdesign/*` package. Adopting it in a new or existing app is a stack choice:
check React 19+, the styling already in use and the migration cost with
[stack selection](../orbyn-stack-selection/SKILL.md), and get the user's decision.
2. **Find the project's CLI.** Use the project's installed invocation: its package
script (`pnpm astryx`, `npm run astryx --`) or local binary. That version's
answers match the installed components. With no installed CLI, read the
[bundled docs](references/upstream/astryx-docs/docs/README.md) (CLI 0.7.12) and say
which version they describe; do not fetch a different CLI just to look something up.
## Build a page
Follow Astryx's own order. Each step is a read-only CLI call until you write code:
1. `astryx build "<idea>"`: the closest page template (or the app shell), two
alternatives, and the blocks and components for what it lacks.
2. `astryx template <name> <path>`: scaffold it, keep its frame and spacing, replace
the content. This writes files; it is part of the change you were asked to make.
3. `astryx component <Name>`: props, examples and the import path for every component
you use. Import each from its own entry.
Astryx's rules, which this library adopts for Astryx projects: start every page from
a template; no raw `div` layout where a component exists; no `style={{}}`; tokens,
never magic values; keep a native element only when its semantics are needed and
Astryx has none. `astryx search`, `astryx docs <topic>` and `astryx doctor` answer the
rest. For anything the designs and templates do not settle, get a design draft first,
as the [lead contract](../orbyn-workflow/references/lead-contract.md#get-a-design-draft-first) says.
## Theme it
A theme is token overrides, not a fork. Map the project's look, or the
[Orbyn house style](../orbyn-ui-design/references/house-style/README.md) when it has
none, into `defineTheme({extends: <built theme>, ...})`: colours, type, radius,
spacing and elevation to their token families, component changes through the
`components` field and `astryx theme targets`. Generate shades with the palette
command rather than by hand. Run `astryx theme build` for server-rendered apps when you
change a theme; after an upgrade, the Dependabot PR rebuilds it. Eject (`swizzle`) a component only when a theme
override cannot express the change, and say why.
Astryx owns light and dark: switch with its `Theme` component's `mode` (`light`, `dark`
or `system`), not with our `data-theme` attribute and script, and never both. Our
outcome rules still hold: no flash of the wrong theme and nothing restyling after
load, which in an Astryx app means wiring the built theme CSS, since a runtime theme's
component overrides flash on hydration.
## Where these rules override Astryx's setup
1. **Never update Astryx by hand.** Do not run `astryx upgrade`, `astryx init` (in any
form, including `--features agents` and `--user`), a global CLI install, or a
package-manager bump of `@astryxdesign/*`, StyleX or a theme package, even when the
CLI or `astryx doctor` suggests it. Versions move only through the project's
Dependabot pull requests, which bump every `@astryxdesign/*` package to one release
together; that PR rebuilds custom themes (`astryx theme build`) and refreshes agent
docs. If something looks stale or missing, report it and point to the open
Dependabot PR or ask the owner to open one; do not fix it in your change.
2. **Project agent files belong to the project.** `init` writes a managed block into
`AGENTS.md` or `CLAUDE.md`, and a global install links a skill into folders such as
`~/.claude/skills/astryx`. Leave both to the owners. If Astryx's own global
`astryx` skill is loaded, treat it as reference; this skill's rules govern.
3. **Adopting Astryx is a decision, not a step.** Adding it to an app that lacks it
goes through [stack selection](../orbyn-stack-selection/SKILL.md) and the owner.
4. **The hosted docs are optional.** Astryx's docs site serves an MCP endpoint. Adding
that MCP server to a host is a configuration change: ask first.
5. **Our checks still apply.** Verify in a real render: light and dark, the widths in
[design rules](../orbyn-ui-design/references/design-rules.md), and for a desktop app
the built window's chrome. Review Astryx code with its rubric (`astryx docs
is-my-code-good`), marking anything you could not see `not inspected`.
## Source and updates
The agent docs of [meta/astryx](https://github.com/meta/astryx/tree/c86484dc57847e7c4d1127810ff1422bc2174d4d/packages/cli/assets/docs)
are bundled unmodified at `c86484d` (CLI 0.7.12), MIT, with the license and a
`snapshot.json` of file hashes. They are `.mjs` modules the CLI prints; read their
`prose`, `list` and `code` entries, and prefer the project's installed CLI whenever
they differ. Never edit or re-download them by hand: `scripts/upstream_watch.py`
opens an issue when Astryx releases, and the refresh goes through
[upstream review](../orbyn-upstream-review/SKILL.md) in a reviewed PR.