# How to Contribute to the Astryx Design System: Complete Guide for Developers > Learn how to contribute to the Astryx design system. Follow our guide to fork the repository, set up dependencies, and submit your code for review. - Repository: [Meta/astryx](https://github.com/facebook/astryx) - Tags: how-to-guide - Published: 2026-07-15 --- **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`](https://github.com/facebook/astryx/blob/main/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. ```bash git clone https://github.com/YOUR_USERNAME/astryx.git cd astryx ``` Install dependencies using pnpm: ```bash 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: ```bash $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/`: ```bash $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: ```bash $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: ```bash $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`](https://github.com/facebook/astryx/blob/main/src/theme.ts). After editing, rebuild the theme assets: ```bash pnpm run build ``` Preview changes in Storybook: ```bash pnpm -F @astryxdesign/storybook dev ``` ## Testing and Validation All contributions must pass the **Vitest** test suites. Run the full test suite across all packages: ```bash pnpm test ``` For targeted testing, run vibe-tests with a sample subset: ```bash pnpm -F @astryxdesign/vibe-tests interactive --sample 5 ``` Execute linting to ensure code style compliance: ```bash 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: ```bash 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 --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/`: ```bash $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 --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.