# How to Contribute to Astryx: A Complete Guide to Meta's React Design System

> Learn how to contribute to Astryx, Meta's React design system. Follow our guide on the 9-phase protocol, core package building, Storybook, and Changesets.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: how-to-guide
- Published: 2026-08-03

---

**Contributing to Astryx requires following a documented 9-phase specification protocol, building the core package before running Storybook, and using Changesets for version management.**

Astryx is Meta's open-source React design system built on React 19+ and StyleX. Whether you're fixing a bug, adding a component, or improving documentation, understanding how to contribute to Astryx ensures your PR meets the project's architectural standards and merges smoothly.

## Understand the Contribution Workflow

The **Contributing wiki** serves as the authoritative source for what Astryx accepts and how decisions get made. According to [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md), all contributors should start with these key wiki pages:

- **API Conventions** – naming patterns, prop composition rules
- **Design Conventions** – token usage, spacing, radius, color, motion
- **Component Specification Protocol** – the 9-phase lifecycle for new components
- **Component Lifecycle** – lab → core, hidden → visible migration paths
- **API Arbitration** – how design debates are resolved
- **Contributing Templates** – grading rubric for docs and demos
- **Contributing with AI** – safe zones and prompt-engineering guidance

The README reinforces this entry point: "We welcome contributions! See **CONTRIBUTING.md** for the full guide."

## Set Up Your Local Development Environment

Astryx pins dependencies strictly. Use these exact versions to avoid common setup failures:

| Requirement | Location | Installation |
|-------------|----------|--------------|
| Node.js 24 | `.nvmrc` | `nvm install` |
| pnpm 11.10.0 | [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) line 71 | `corepack enable` or `npm i -g pnpm@11` |

Run this bootstrap sequence from [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) lines 85-99:

```bash
git clone https://github.com/facebook/astryx.git
cd astryx
corepack enable                    # auto-installs correct pnpm

pnpm install
pnpm -F @astryxdesign/core build   # required before Storybook works

```

Skipping the core build causes Storybook module resolution errors—a common troubleshooting item covered later.

## Navigate the Project Structure

Understanding where code lives prevents misplaced contributions. From [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) lines 162-176:

```

astryx/
├── apps/
│   ├── storybook/          # Component playground (localhost:6006)

│   └── docsite/            # Next.js documentation (localhost:3000)

├── packages/
│   ├── core/               # Published components (Button, Input, etc.)

│   ├── cli/                # Astryx CLI tooling

│   ├── lab/                # Experimental components

│   └── themes/             # Theme packages

└── internal/               # Shared test utilities

```

Components destined for release must live in `packages/core/src/`. Experimental work starts in `packages/lab/`.

## Add a New Component Following the 9-Phase Protocol

Astryx enforces strict scaffolding through [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) lines 216-290:

1. **Create directory**: `packages/core/src/MyComponent`
2. **Implement component**: [`MyComponent.tsx`](https://github.com/facebook/astryx/blob/main/MyComponent.tsx) with `forwardRef`, JSDoc, and `@example` block (lines 216-244)
3. **Write tests**: [`MyComponent.test.tsx`](https://github.com/facebook/astryx/blob/main/MyComponent.test.tsx) using Vitest + React Testing Library (lines 250-260)
4. **Add stories**: [`MyComponent.stories.tsx`](https://github.com/facebook/astryx/blob/main/MyComponent.stories.tsx) for Storybook (lines 264-274)
5. **Export publicly**: Edit [`packages/core/src/index.ts`](https://github.com/facebook/astryx/blob/main/packages/core/src/index.ts) (lines 288-290)
6. **Validate exports**: Run `pnpm sync:exports:check`

The export list auto-generates via [`scripts/sync-exports.js`](https://github.com/facebook/astryx/blob/main/scripts/sync-exports.js). This script runs as part of CI, so local checks catch omissions early.

## Run the Full Test and Quality Suite

Astryx maintains multiple quality gates. Execute these from [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) scripts (line 19 onward):

| Command | Purpose |
|---------|---------|
| `pnpm test` | Unit and integration tests (Vitest) |
| `pnpm test:watch` | Continuous feedback during development |
| `pnpm test:coverage` | HTML coverage reports |
| `pnpm test:screenshots` | Visual regression with Vibe-tests |
| `pnpm a11y:audit` | Axe-core audit against [`.github/a11y-baseline.json`](https://github.com/facebook/astryx/blob/main/.github/a11y-baseline.json) |
| `pnpm lint` | ESLint + Prettier |

Accessibility audits fail on new violations. Update the baseline only for intentional exceptions using `pnpm a11y:baseline` (lines 447-454).

## Manage Versioning with Changesets

Astryx uses a custom Changesets wrapper: `pnpm changeset:new`. Categories drive semver behavior:

- **breaking** → minor bump (0.x behavior)
- **component**, **feat**, **fix**, **perf**, **docs**, **chore** → patch bump

All publishable packages live in a fixed group, so any change co-bumps every package.

Interactive changeset creation:

```bash
pnpm changeset:new

```

Non-interactive for automation:

```bash
pnpm changeset:new --category fix --summary "Fix Button hover state" --pr 2717 --contributor yourhandle

```

## Submit a Pull Request That Gets Merged

Follow the PR workflow from [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) lines 331-349:

1. Branch from `main`
2. Implement changes with comprehensive tests
3. Run `pnpm test`, `pnpm lint`, and `pnpm a11y:audit`
4. Add a changeset if modifying released packages
5. Open PR (draft until ready)
6. **Enable "Allow edits by maintainers"**—critical for rebase workflows
7. Apply appropriate labels: `good first issue`, `help wanted`, `breaking`

Maintainers can rebase your branch directly when this permission is granted, eliminating back-and-forth delays.

## Troubleshoot Common Setup Issues

From [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) lines 558-580:

| Symptom | Cause | Solution |
|---------|-------|----------|
| `pnpm: command not found` | Missing package manager | `corepack enable` or `npm i -g pnpm@11` |
| Storybook "module not found" | Core package unbuilt | `pnpm -F @astryxdesign/core build` |
| Accessibility baseline failures | Unintentional violations | Review output, update baseline only if intentional |

## Key Files to Bookmark

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) | Complete workflow, setup, testing, PR process |
| `.nvmrc` | Node version 24 |
| [`package.json`](https://github.com/facebook/astryx/blob/main/package.json) | pnpm@11.10.0 declaration, all scripts |
| [`scripts/sync-exports.js`](https://github.com/facebook/astryx/blob/main/scripts/sync-exports.js) | Auto-generated exports validation |
| `packages/core/src/` | All publishable components |
| [`.github/a11y-baseline.json`](https://github.com/facebook/astryx/blob/main/.github/a11y-baseline.json) | Accessibility audit baseline |

---

## Summary

- **Start with the wiki**: API and design conventions govern every contribution to Astryx
- **Bootstrap correctly**: Node 24, pnpm 11.10.0, and `core build` before Storybook
- **Follow 9-phase protocol**: Directory → implementation → tests → stories → export → sync check
- **Quality gates matter**: Tests, lint, accessibility audits, and changesets are required
- **Enable maintainer edits**: Speeds review by allowing direct rebase operations

---

## Frequently Asked Questions

### Does Astryx accept external contributions?

Yes. The repository explicitly welcomes contributions through [`CONTRIBUTING.md`](https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md) and maintains `good first issue` and `help wanted` labels to guide new contributors toward manageable work.

### Why does Storybook fail with "module not found" errors?

The core package must be built before Storybook can resolve component imports. Run `pnpm -F @astryxdesign/core build` after `pnpm install` and before starting Storybook.

### What happens if I forget to add a changeset?

CI enforces changeset rules for any PR affecting released packages. The PR checks will fail with a prompt to run `pnpm changeset:new` and commit the resulting file.

### How do I know if my component belongs in core or lab?

Experimental components with unfinalized APIs start in `packages/lab/`. Once they complete the 9-phase specification protocol and migrate through the component lifecycle, they graduate to `packages/core/` for publication.