How to Contribute to the Astryx Design System: Complete Guide for Developers

To contribute to the Astryx design system, fork the facebook/astryx repository, install dependencies with pnpm via Corepack, bootstrap the monorepo using the $ASTRYX CLI, create a feature branch for your changes, and submit a pull request after running the full Vitest suite and linting.

Astryx is Facebook’s modular design system for building internal tools and products, maintained as a monorepo containing core UI components, themes, and developer tooling. To contribute to the Astryx design system, you must use the $ASTRYX CLI for component discovery, pnpm for package management, and Vitest for testing. This guide covers the exact workflow defined in CONTRIBUTING.md and demonstrates how to work with the source code in packages/core/ and packages/themes/.

Prerequisites and Repository Setup

Begin by forking the repository on GitHub and cloning your fork locally. The project requires pnpm managed via Corepack for consistent dependency resolution across the monorepo.

git clone https://github.com/YOUR_USERNAME/astryx.git
cd astryx

Install dependencies using pnpm:

pnpm install

Bootstrapping the Monorepo

After installation, initialize the repository using the Astryx CLI to ensure all packages are correctly linked and documentation is generated. Run these commands in sequence:

$ASTRYX help
$ASTRYX component --list
$ASTRYX upgrade --apply

This bootstrap process validates the packages/ directory structure and syncs generated documentation (*.doc.mjs files) with the current source code.

Creating and Editing Components

Generating New Components

Use the CLI to scaffold a new component skeleton. Pipe the output to create the source file in packages/core/src/:

$ASTRYX component Button --dense > packages/core/src/Button/Button.tsx

Edit the generated file and create a matching documentation file at packages/core/src/Button/Button.doc.mjs. Verify registration by listing components:

$ASTRYX component --list | grep Button

Component Documentation Standards

All components must include a *.doc.mjs file alongside their source. View existing component APIs before editing by using the dense flag:

$ASTRYX component Switch --dense

This outputs props, variants, usage examples, and the exact path to the source documentation file.

Working with Theme Packages

Theme packages reside in packages/themes/. To update a theme, navigate to the specific theme directory (e.g., packages/themes/stone) and modify the theme definition in src/theme.ts.

After editing, rebuild the theme assets:

pnpm run build

Preview changes in Storybook:

pnpm -F @astryxdesign/storybook dev

Testing and Validation

All contributions must pass the Vitest test suites. Run the full test suite across all packages:

pnpm test

For targeted testing, run vibe-tests with a sample subset:

pnpm -F @astryxdesign/vibe-tests interactive --sample 5

Execute linting to ensure code style compliance:

pnpm lint

The repository enforces StyleX-centric CSS conventions and JSDoc documentation standards. All Vitest suites must pass before submitting a pull request.

Submitting Your Contribution

Create a feature branch with a descriptive name:

git checkout -b feature/your-change-name

Commit your changes following the repository’s formatting guidelines. Push the branch to your fork and open a Pull Request against the main branch. Follow the PR template by providing a clear description, linking relevant issues, and including screenshots for visual changes. Address review feedback promptly; approved PRs are merged automatically.

Summary

• Fork and clone the facebook/astryx repository, then run pnpm install to initialize dependencies.
• Bootstrap the monorepo using $ASTRYX help, $ASTRYX component --list, and $ASTRYX upgrade --apply to link packages and sync documentation.
• Generate components with $ASTRYX component <Name> --dense and create corresponding *.doc.mjs files in packages/core/src/.
• Test thoroughly using pnpm test (Vitest) and pnpm lint before submitting; all suites must pass.
• Follow StyleX and JSDoc conventions for CSS and documentation, and adhere to the PR template requirements.

Frequently Asked Questions

What package manager does Astryx use?

Astryx uses pnpm managed via Corepack for all package management operations. This ensures consistent dependency resolution across the monorepo’s packages/ directory. Install dependencies with pnpm install and use pnpm filters (e.g., pnpm -F @astryxdesign/storybook) to run commands in specific packages.

How do I generate a new component skeleton?

Use the $ASTRYX CLI with the --dense flag to output a complete component template. Pipe the result to your target file in packages/core/src/:

$ASTRYX component Button --dense > packages/core/src/Button/Button.tsx

Where does component documentation live?

Documentation co-locates with source code as *.doc.mjs files (e.g., packages/core/src/Button/Button.doc.mjs). View existing documentation using $ASTRYX component <Name> --dense, which displays props, variants, and the file path to the documentation source.

What testing framework does Astryx use?

The repository uses Vitest for all testing. Run the complete suite with pnpm test or target specific packages using pnpm filters (e.g., pnpm -F @astryxdesign/vibe-tests interactive --sample 5). All tests must pass before a pull request can be merged.

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