Astryx

Skill Firzus/agent-skills/skills/web/astryx

Astryx (@astryxdesign) — Meta's open-source, agent-ready React + StyleX design system. Covers setup (npm packages, npx astryx init, StyleX compiler), the agent discovery loop (astryx template/component/docs, MCP server, --dense), per-component subpath imports, the xstyle styling order, design tokens, the Theme provider and defineTheme theming, cascade-layer CSS wiring, Tailwind and library interop, layout primitives, and incremental migration. Use when the user mentions Astryx, @astryxdesign, npx astryx, xstyle, defineTheme, or wants to set up, build UI with, theme, review, or migrate to the Astryx design system.From its SKILL.md

Install

npx -y skills add Firzus/agent-skills --skill astryx

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

6.0 KB, ~1.5k tokens by cl100k_base, as published. Nobody here has run it

Astryx Design System

Astryx is Meta's open-source React + StyleX design system: 150+ accessible, themeable components with pre-compiled CSS, distributed as @astryxdesign/* npm packages and driven by a CLI (npx astryx) plus a hosted MCP server. Its defining trait is agent-ready — humans and AI build from the same API, so let the CLI/MCP be your source of truth, not the HTML docsite or memory. Astryx is in beta (v0.x); package names and flags may still shift.

Apply this skill when setting up, building UI with, theming, reviewing, or migrating an Astryx project.

Done when: every component is imported from its own subpath and reads design tokens (never hardcoded colors/spacing); styling follows the xstyle → Tailwind → className order with no !important; exactly one <Theme> provider owns color mode; the cascade-@layer line is declared once before CSS imports; swizzled components have a StyleX build plugin wired; and npx astryx doctor reports no failures.

Setup

# 1. Install (npm or pnpm — both are shown in the docs)
npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli

# 2. Scaffold: installs packages, wires theming, writes AI agent docs
npx astryx init

# 3. Generate agent context for THIS repo's installed version
npx astryx init --features agents --agent claude   # -> CLAUDE.md
#   ...--agent cursor -> .cursorrules   |   --agent codex -> AGENTS.md

# 4. Verify the setup (CI-friendly exit code)
npx astryx doctor

Do not invent Node or React version floors — the docs print none. Run npx astryx doctor to surface environment problems instead. Full install, framework wiring, and the mandatory StyleX-compiler rules: → setup.md.

The discovery loop

The single biggest correctness lever. Never write Astryx UI from memory — query the installed version first, in this order:

npx astryx template --list                 # 1. find a page/block pattern
npx astryx template <Name> --skeleton      # 2. inspect its layout
npx astryx component <Name>                 # 3. read real props + usage

Add --dense for token-efficient output in context-limited tools, --json for machine-readable output in scripts/CI. The same reference is reachable over the hosted MCP server (search/get tools). Full CLI surface, MCP config, and agent workflows: → cli-and-agents.md.

Golden rules

High-leverage rules. Each links to deeper reference.

Discover before you write. Run the template→skeleton→component loop above; don't guess props or import paths. There is no astryx add — add UI via template <name> [path], swizzle <Component>, or plain imports. → cli-and-agents.md
Per-component subpath imports. import {Button} from '@astryxdesign/core/Button' — never a barrel root. → styling-components.md
Styling order of preference. xstyle (StyleX from stylex.create() only — never inline objects or classNames) → Tailwind utilities → className/style. No !important (xstyle merges last). Guard every StyleX :hover with @media (hover: hover). → styling-components.md
Tokens, never literals. Use var(--color-*/--spacing-*/--radius-*) or the typed *Vars objects so theme + light/dark resolve automatically. Sass variables are compile-time and break theming. → theming-tokens.md
One color-mode owner. The <Theme mode> provider owns light/dark (mode default 'system'); never run a second dark-mode provider. Theme, useTheme, and defineTheme are all exported from both @astryxdesign/core and @astryxdesign/core/theme — either import path is fine (verified v0.1.7). → theming-tokens.md
Declare the cascade layer once. Put @layer reset, theme, base, astryx-base, astryx-theme, components, utilities; before your CSS imports — unlayered or late styles silently override Astryx. → styling-components.md
Swizzle needs a StyleX compiler. Swizzled (copied-source) components render completely unstyled with no error if the bundler lacks a StyleX plugin. Pre-compiled components need none. Wire the plugin for your bundler — the Next.js Turbopack and webpack paths differ (per-bundler table in setup.md); on Next.js, never add @stylexjs/babel-plugin (disables SWC, breaks next/font).
Migrate the frame, not the classes. Incremental, one route at a time: wrap root in Theme, fix @layer order, then replace primitives. → migration-layout-i18n.md

Reference map

Load on demand:

When	File
Install, `npx astryx init`, packages, StyleX compiler per bundler, browser support	setup.md
Full CLI command surface, discovery loop, MCP server, agent context files, `--dense`/`--json`	cli-and-agents.md
Import conventions, `xstyle`, cascade layers, `data-*` targeting, Tailwind & library interop	styling-components.md
`<Theme>`, `defineTheme`, dark mode, theme packages, the design-token catalog	theming-tokens.md
Design principles, layout primitives (AppShell/Layout), migration path, i18n	migration-layout-i18n.md

</content> </invoke>

What ships with it: 5 files

24.2 KB alongside SKILL.md