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

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, 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 line 71	corepack enable or npm i -g pnpm@11

Run this bootstrap sequence from CONTRIBUTING.md lines 85-99:

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 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 lines 216-290:

1. Create directory: packages/core/src/MyComponent
2. Implement component: MyComponent.tsx with forwardRef, JSDoc, and @example block (lines 216-244)
3. Write tests: MyComponent.test.tsx using Vitest + React Testing Library (lines 250-260)
4. Add stories: MyComponent.stories.tsx for Storybook (lines 264-274)
5. Export publicly: Edit 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. 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 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
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:

pnpm changeset:new

Non-interactive for automation:

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 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 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	Complete workflow, setup, testing, PR process
.nvmrc	Node version 24
package.json	pnpm@11.10.0 declaration, all scripts
scripts/sync-exports.js	Auto-generated exports validation
packages/core/src/	All publishable components
.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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}