### Install Dependencies and Run Example App

Source: https://github.com/facebook/astryx/wiki/Testing-Example-Apps

Install the project dependencies and then build and preview the Vite app, or build and start the Next.js app. Ensure to use npx for commands.

```bash
npm install
# Vite:
npx vite build && npx vite preview
# Next.js:
npx next build && npx next start
```

--------------------------------

### Install Dependencies and Run Dev Server

Source: https://github.com/facebook/astryx/wiki/Docsite-Architecture

Navigate to the docsite directory, install dependencies, and start the development server. The `predev` script automatically regenerates data before starting.

```bash
cd apps/docsite
pnpm install
pnpm dev          # Runs generate + next dev
```

--------------------------------

### Project Installation and Development Commands

Source: https://github.com/facebook/astryx/blob/main/apps/example-nextjs-tailwind/README.md

Install project dependencies using pnpm and start the development server. The command `pnpm dev` can be used directly or by navigating to the example directory.

```bash
pnpm install
pnpm dev  # or: cd apps/example-nextjs-tailwind && npx next dev
```

--------------------------------

### Install XDS Core and Theme

Source: https://github.com/facebook/astryx/blob/main/packages/core/README.md

Install the core XDS package and a theme using npm. This is the first step for any framework setup.

```bash
npm install @astryxdesign/core @astryxdesign/theme-neutral
```

--------------------------------

### Install Latest npm and Login

Source: https://github.com/facebook/astryx/blob/main/docs/release.md

Ensure you have the latest npm version and are logged in to the npm registry before running the setup script.

```bash
npm i -g npm@latest
npm login --registry https://registry.npmjs.org
```

--------------------------------

### Install @astryxdesign/theme-matcha

Source: https://github.com/facebook/astryx/blob/main/packages/themes/matcha/README.md

Use npm to install the theme package.

```bash
npm install @astryxdesign/theme-matcha
```

--------------------------------

### Clone and Install Astryx Dependencies

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Clone the Astryx repository, install dependencies using pnpm, and build the core package before starting Storybook.

```bash
# Clone the repo
git clone https://github.com/facebook/astryx.git
cd astryx

# Install dependencies
pnpm install

# Build core package first (required for Storybook)
pnpm -F @astryxdesign/core build

# Start Storybook for component development
cd apps/storybook
pnpm dev
```

--------------------------------

### Start Astryx Storybook

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Navigate to the Storybook directory and start the development server to view and interact with components.

```bash
cd apps/storybook
pnpm dev
```

--------------------------------

### Install @astryxdesign/build

Source: https://github.com/facebook/astryx/blob/main/packages/build/README.md

Install the core build package and the StyleX Babel plugin for your project.

```bash
npm install -D @astryxdesign/build @stylexjs/babel-plugin @babel/core
```

--------------------------------

### Install Dependencies

Source: https://github.com/facebook/astryx/blob/main/apps/example-nextjs/README.md

Install the necessary @astryxdesign/core and Next.js dependencies.

```bash
npm install @astryxdesign/core @astryxdesign/theme-neutral next react react-dom
npm install --save-dev @types/react @types/react-dom typescript
```

--------------------------------

### Quick Start Development Mode

Source: https://github.com/facebook/astryx/blob/main/apps/sandbox/README.md

Build the core package once and then start the sandbox. Edits to core components require a manual rebuild.

```bash
pnpm dev:sandbox
```

--------------------------------

### Install @astryxdesign/theme-stone

Source: https://github.com/facebook/astryx/blob/main/packages/themes/stone/README.md

Install the theme package using npm.

```bash
npm install @astryxdesign/theme-stone
```

--------------------------------

### Install and Run XDS Docsite

Source: https://github.com/facebook/astryx/blob/main/apps/docsite/README.md

Commands to install dependencies, build packages, navigate to the docsite directory, and start the development server. The 'generate' command extracts monorepo data.

```bash
pnpm install     # from repo root
pnpm build       # build all packages (themes need built exports)
cd apps/docsite
pnpm generate    # extract data from the monorepo into src/generated/
pnpm dev         # start the dev server
```

--------------------------------

### Install @astryxdesign/theme-neutral

Source: https://github.com/facebook/astryx/blob/main/packages/themes/neutral/README.md

Install the neutral theme package using npm. This command fetches and installs the necessary files for the theme.

```bash
npm install @astryxdesign/theme-neutral
```

--------------------------------

### Copy Example App Files

Source: https://github.com/facebook/astryx/wiki/Testing-Example-Apps

Copy the example app files to the test directory, excluding large or problematic directories like node_modules and build outputs. Use rsync for efficient copying.

```bash
# Vite:
rsync -a --exclude node_modules --exclude dist /path/to/astryx/apps/example-vite/ .
# Next.js:
rsync -a --exclude node_modules --exclude .next /path/to/astryx/apps/example-nextjs/ .
```

--------------------------------

### Install Dependencies

Source: https://github.com/facebook/astryx/blob/main/apps/example-nextjs-stylex/README.md

Install necessary dependencies for @astryxdesign/core, StyleX, Next.js, and React. Includes both production and development dependencies.

```bash
npm install @stylexjs/stylex @astryxdesign/core @astryxdesign/theme-neutral next react react-dom
npm install --save-dev @stylexjs/babel-plugin @stylexjs/postcss-plugin \
  @babel/preset-react @babel/preset-typescript typescript @types/react @types/react-dom
```

--------------------------------

### Run Trusted Publishing Setup Script

Source: https://github.com/facebook/astryx/blob/main/docs/release.md

Execute the setup script directly with Node.js, passing any necessary flags.

```bash
node scripts/npm/setup-trusted-publishing.mjs [flags]
```

--------------------------------

### Naming Convention Examples

Source: https://github.com/facebook/astryx/blob/main/internal/vibe-tests/ideals/README.md

Illustrates the application of the naming convention with concrete examples for specific, viewport-only, and generic fallback image files.

```text
- `cwm-1__desktop__light.png`: specific to desktop + light
- `ty-3__desktop.png`: desktop only, used for both light and dark
- `dd-3.png`: fallback for all viewport/theme combos
```

--------------------------------

### Start Local Development Server

Source: https://github.com/facebook/astryx/blob/main/apps/docsite/src/content/blog/README.md

Navigate to the `apps/docsite` directory and run `pnpm dev` to start the local development server. This command also runs `pnpm generate` first.

```bash
cd apps/docsite
pnpm dev            # runs `pnpm generate` first, then starts Next.js
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/facebook/astryx/blob/main/apps/example-vite/README.md

Installs StyleX, Astryx core and theme, React, and development dependencies for Vite and TypeScript.

```bash
npm install @stylexjs/stylex @astryxdesign/core @astryxdesign/theme-neutral react react-dom
npm install --save-dev @stylexjs/unplugin @vitejs/plugin-react typescript 
  @types/react @types/react-dom vite
```

--------------------------------

### Install Core Packages and CLI

Source: https://github.com/facebook/astryx/blob/main/README.md

Installs the core Astryx design system packages and the CLI tool using pnpm, npm, or yarn.

```bash
# pnpm
pnpm add @astryxdesign/core @astryxdesign/theme-neutral
pnpm add -D @astryxdesign/cli

# npm
npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

# yarn
yarn add @astryxdesign/core @astryxdesign/theme-neutral
yarn add -D @astryxdesign/cli
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/facebook/astryx/blob/main/internal/vibe-tests/environments/project-astryx/README.md

Install development dependencies for the project if the Astryx CLI is not available.

```bash
npm install --include=dev
```

--------------------------------

### Install Vega Dependencies

Source: https://github.com/facebook/astryx/blob/main/packages/vega/README.md

Install the @astryxdesign/vega package along with vega and vega-lite to use the charting components.

```bash
pnpm add @astryxdesign/vega vega vega-lite
```

--------------------------------

### Setup and Generate Code for Nightly Test

Source: https://github.com/facebook/astryx/wiki/Night-Watch-Vibe-Test-Runner

Runs the setup script to create agent project directories and task files. Verifies the contents of generated task files and specific Astryx agent project directories before spawning sub-agents.

```bash
# Run setup (creates iterations + per-agent project dirs)
node internal/vibe-tests/src/setup-nightly.mjs --sample 10
```

```bash
ls <project-dir>/node_modules/.bin/xds  # symlink exists
ls <project-dir>/node_modules/@xds/core/README.md  # docs accessible
```

--------------------------------

### Install pnpm with Alternative Methods

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Use these commands if pnpm fails to download its binary due to network restrictions. Homebrew, standalone installer, and npm are alternative methods.

```bash
brew install pnpm                        # Homebrew (macOS)
```

```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -  # Standalone installer
```

```bash
npm install -g pnpm@10                   # Via npm
```

--------------------------------

### Install Vite Dependencies

Source: https://github.com/facebook/astryx/blob/main/packages/build/README.md

For Vite projects, also install the StyleX unplugin.

```bash
npm install -D @stylexjs/unplugin
```

--------------------------------

### Install Butter Theme

Source: https://github.com/facebook/astryx/blob/main/packages/themes/butter/README.md

Install the Butter theme package using npm.

```bash
npm install @astryxdesign/theme-butter
```

--------------------------------

### Minimal Astryx Consumer Setup

Source: https://github.com/facebook/astryx/wiki/Distribution

Import the core CSS once in your application's root and then use Astryx components. This setup requires no additional Babel or PostCSS configuration.

```tsx
// 1. Import CSS (once, in your app root)
import '@xds/core/xds.css';

// 2. Use components
import { Button } from '@xds/core';

<Button variant="primary" className="mt-4">Save</Button>
```

--------------------------------

### Install Dependencies

Source: https://github.com/facebook/astryx/blob/main/apps/sandbox/README.md

Install project dependencies using npm. This command also generates AGENTS.md.

```bash
npm install
```

--------------------------------

### Changeset File Example

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

An example of a generated Changeset Markdown file. It specifies the package, the type of change, a summary, and the contributor.

```markdown
---
'@astryxdesign/core': patch
---

[fix] Spinner inherits the variant foreground on themed buttons (#2717)
@yourhandle
```

--------------------------------

### Set Up Standalone Test Directory

Source: https://github.com/facebook/astryx/wiki/Testing-Example-Apps

Create and navigate to a new directory for testing the Astryx example app as an external consumer.

```bash
mkdir ~/astryx-test-app
cd ~/astryx-test-app
```

--------------------------------

### Get PR Diff using GitHub CLI

Source: https://github.com/facebook/astryx/wiki/Night-Watch-QA

Use this command to fetch the code differences for a specific pull request. Ensure you have the GitHub CLI installed and authenticated.

```bash
gh pr diff {number} --repo facebook/astryx
```

--------------------------------

### Page Layout with Header and Navigation

Source: https://github.com/facebook/astryx/wiki/Contributing-Templates

Use the `header` slot for the page title and actions, and the `start` slot for in-page section navigation. This example demonstrates a settings page structure.

```tsx
'use client';

import {useState} from 'react';
import {
  Layout,
  LayoutContent,
  LayoutHeader,
  LayoutPanel,
} from '@xds/core/Layout';
import {Heading} from '@xds/core/Text';
import {List, ListItem} from '@xds/core/List';

const SECTIONS = ['Profile', 'Account', 'Notifications'];

export default function MyTemplate() {
  const [active, setActive] = useState('Profile');
  return (
    <Layout
      height="auto"
      header={
        <LayoutHeader hasDivider>
          <Heading level={1}>Settings</Heading>
        </LayoutHeader>
      }
      start={
        <LayoutPanel hasDivider={false} padding={0}>
          <List density="balanced">
            {SECTIONS.map(s => (
              <ListItem
                key={s}
                label={s}
                isSelected={active === s}
                onClick={() => setActive(s)}
              />
            ))}
          </List>
        </LayoutPanel>
      }
      content={
        <LayoutContent padding={4}>
          {/* Section content for `active` */}
        </LayoutContent>
      }
    />
  );
}

```

--------------------------------

### Run Trusted Publishing Setup Script (Audit and Bootstrap)

Source: https://github.com/facebook/astryx/blob/main/docs/release.md

Perform an audit of packages and bootstrap any missing ones, followed by setting up trust configurations.

```bash
node scripts/npm/setup-trusted-publishing.mjs --bootstrap --setup-trust
```

--------------------------------

### Run Astryx Doctor Health Checks

Source: https://github.com/facebook/astryx/blob/main/packages/cli/README.md

Execute the `astryx doctor` command to diagnose your project setup. It checks Node.js version, core package installation and alignment, theme packages, configuration files, AI agent documentation, peer dependencies, and the package manager.

```bash
$ astryx doctor
astryx doctor — diagnosing your setup

  ✓ Node.js version
      Node v22.13.0 meets the minimum (>=22.13.0).
  ✓ @astryxdesign/core installed
      @astryxdesign/core resolved (v0.0.14).
  ✓ @astryxdesign/core <-> @astryxdesign/cli alignment
      @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
  ⚠ Theme packages
      No @astryxdesign/theme-* packages are installed.
      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.
  ℹ astryx.config.mjs
      No astryx.config.mjs found — using defaults.
  ℹ AI agent docs
      No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
      → fix: Generate agent docs with `astryx init --features agents`.
  ✓ @astryxdesign/core peer dependencies
      All peer dependencies satisfied (react, react-dom).
  ℹ Package manager
      Detected package manager: yarn.

Summary: 4 passed, 1 warning, 0 failures, 3 info

No failures — but review the ⚠ warnings above when you can.
```

--------------------------------

### Install pnpm via standalone installer

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Installs pnpm version 10.33.4 using a standalone script. This method does not require Node.js or npm.

```bash
curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=10.33.4 sh -
```

--------------------------------

### Install Y2K Theme

Source: https://github.com/facebook/astryx/blob/main/packages/themes/y2k/README.md

Install the theme package using npm.

```bash
npm install @astryxdesign/theme-y2k
```

--------------------------------

### Install Chocolate Theme

Source: https://github.com/facebook/astryx/blob/main/packages/themes/chocolate/README.md

Install the theme package using npm.

```bash
npm install @astryxdesign/theme-chocolate
```

--------------------------------

### Theme and Link Provider Setup

Source: https://github.com/facebook/astryx/blob/main/apps/example-nextjs-stylex/README.md

Set up the Theme and LinkProvider components from @astryxdesign/core to provide theme context and Next.js Link integration.

```tsx
'use client';
import Link from 'next/link';
import {Theme} from '@astryxdesign/core/theme';
import {LinkProvider} from '@astryxdesign/core/Link';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';

export function Providers({children}) {
  return (
    <Theme theme={neutralTheme}>
      <LinkProvider component={Link}>{children}</LinkProvider>
    </Theme>
  );
}
```

--------------------------------

### Get All Components in Brief Format

Source: https://github.com/facebook/astryx/wiki/Distribution

Retrieves all components in a brief format, useful for providing context to AI models. This command lists components concisely.

```bash
npx xds component --brief-all
```

--------------------------------

### Add CSS Entry Point

Source: https://github.com/facebook/astryx/blob/main/apps/example-vite/README.md

Create a minimal `index.css` file and import it in `main.tsx` to ensure StyleX has a CSS asset to append to.

```javascript
import './index.css';
```

--------------------------------

### Basic Astryx CLI Commands

Source: https://github.com/facebook/astryx/blob/main/packages/cli/README.md

Common commands to get help, search for components, view component documentation, and list templates.

```bash
npx astryx --help
npx astryx search button
npx astryx component Button
npx astryx docs tokens
npx astryx docs migration
npx astryx template --list
```

--------------------------------

### Verify Node.js and pnpm installation

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Verifies that Node.js and pnpm are installed and accessible in the current environment by checking their versions.

```bash
node --version
pnpm --version
```

--------------------------------

### Enable and Install pnpm

Source: https://github.com/facebook/astryx/blob/main/README.md

Enables Corepack to automatically manage the correct pnpm version and installs project dependencies.

```bash
corepack enable
pnpm install
```

--------------------------------

### View Component Documentation

Source: https://github.com/facebook/astryx/wiki/Distribution

This command displays documentation for a specific component. Replace `<Name>` with the actual component name.

```bash
npx xds component <Name>
```

--------------------------------

### Example Hardening Issue Structure

Source: https://github.com/facebook/astryx/wiki/Hardening-Audit-Guide

An example of a filled-out hardening issue, showing how components and their findings are listed with status.

```markdown
### Status & Feedback (4)

- [ ] Badge
  - [ ] P1: Height should be 20px, currently 24.5px
  - [ ] P2: Font weight and type are different from WWW
  - [ ] P2: Dark mode color is too faint
- [ ] Spinner
  - [ ] P0: Storybook description is weird AI-generated text
  - [ ] P2: Should have a way to render the label together with the spinner
- [x] EmptyState ✅
- [x] Token ✅

### Navigation (3)

- [ ] SideNav
  - [ ] P0: Using inline style={{width: 16}} instead of width={16} prop
  - [ ] P0: Title should have same interactive area as nav items (8px from edge, not 4px)
  - [ ] P2: Needs visual adjustment when icon is not provided in header
  - [ ] P3: 2px gap needed between page nav items
- [ ] Breadcrumbs
  - [ ] P1: Leaf node appears offset, not vertically centered
  - [ ] P1: Missing chevron variant
- [x] TopNav ✅
```

--------------------------------

### Generate Component Documentation

Source: https://github.com/facebook/astryx/blob/main/packages/core/README.md

Use this command to generate full API documentation for a specific component or list all available components.

```bash
node node_modules/@astryxdesign/core/docs.mjs Button        # full docs for a component
```

```bash
node node_modules/@astryxdesign/core/docs.mjs --list         # list all components
```

```bash
node node_modules/@astryxdesign/core/docs.mjs --list --brief  # brief summaries
```

--------------------------------

### Bootstrap and register trusted publishing

Source: https://github.com/facebook/astryx/wiki/Release-Process

One-time local setup for adding a new package. This involves auditing, claiming the package name, and registering the release workflow as a trusted publisher.

```bash
pnpm run setup-trusted-publishing
pnpm run setup-trusted-publishing --bootstrap --setup-trust --workflow release.yml
```

--------------------------------

### Install Gothic Theme

Source: https://github.com/facebook/astryx/blob/main/packages/themes/gothic/README.md

Install the gothic theme package using npm. This is the first step to using the theme in your project.

```bash
npm install @astryxdesign/theme-gothic
```

--------------------------------

### Testing Setup

Source: https://github.com/facebook/astryx/blob/main/apps/docsite/README.md

Instructions for running tests in the Astryx project. Tests are located in `src/__tests__/data-extraction.test.ts` and validate generated registries. Ensure you run `pnpm generate` before executing tests, as they depend on the generated files.

```bash
pnpm generate

```

--------------------------------

### Install Axtryx Design Dependencies

Source: https://github.com/facebook/astryx/blob/main/apps/example-nextjs-source/README.md

Install the core Axtryx Design packages, theme, and necessary build tools using npm.

```bash
npm install @stylexjs/stylex @astryxdesign/core @astryxdesign/theme-neutral next react react-dom
npm install -D @astryxdesign/build @stylexjs/babel-plugin @babel/core autoprefixer typescript
```

--------------------------------

### Install pnpm via Homebrew

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Installs pnpm using the Homebrew package manager on macOS. This is a convenient option for macOS users.

```bash
brew install pnpm
```

--------------------------------

### Vibe-test command execution steps

Source: https://github.com/facebook/astryx/blob/main/CLAUDE.md

This outlines the multi-step process for executing vibe-tests, involving setup, parallel agent execution for code generation and self-evaluation, and result aggregation.

```bash
pnpm -F @astryxdesign/vibe-tests interactive --sample <count>
```

```bash
pnpm -F @astryxdesign/vibe-tests aggregate --iteration <id>
```

--------------------------------

### Install pnpm via npm

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Installs pnpm version 10 globally using npm. This is an alternative method if Corepack is not used.

```bash
npm install -g pnpm@10
```

--------------------------------

### List Astryx Components via CLI

Source: https://github.com/facebook/astryx/wiki/System-Architecture

Use the CLI to list all components by category. This command helps AI assistants discover available components.

```bash
npx xds component --list
```

--------------------------------

### Create Production Build

Source: https://github.com/facebook/astryx/blob/main/apps/example-vite/README.md

Run this command to generate an optimized production build of your application.

```bash
npm run build
```

--------------------------------

### Run Local Development Server

Source: https://github.com/facebook/astryx/wiki/Contributing-Templates

Execute this command from the repository root to start the local development server. It enables hot reloading for immediate feedback on changes.

```bash
# From the repo root
pnpm --filter @xds/sandbox dev

# All templates and blocks:
# http://localhost:3000/templates/<slug>/

# Official Templates table:
# http://localhost:3000/templates/
```

--------------------------------

### Start Vite Dev Server

Source: https://github.com/facebook/astryx/blob/main/apps/example-vite/README.md

Use this command to start the development server with Hot Module Replacement (HMR) enabled for rapid development.

```bash
npm run dev
```

--------------------------------

### Install Node.js via nvm

Source: https://github.com/facebook/astryx/blob/main/CONTRIBUTING.md

Installs Node.js version 22 using the Node Version Manager (nvm). This is the recommended method for managing Node.js versions.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 22
```

--------------------------------

### Night Watch QA - Tier 1 Example: Doing Work

Source: https://github.com/facebook/astryx/wiki/Night-Watch-QA

Example of a review comment indicating completed work, focusing on implementation details and component extraction.

```text
Done — replaced the hand-rolled overlay/panel with Dialog. Using 
purpose="info" so backdrop click and Escape are handled natively by 
the dialog element.
```

```text
Done — extracted three sub-components with displayName:
- CommandPaletteItem — renders a single command option row
- CommandPaletteShortcutRow — renders a shortcut display row
- CommandPaletteGroup — renders a group with header and divider
```

--------------------------------

### Full Guide Location

Source: https://github.com/facebook/astryx/wiki/Agent-Init-Prompt-Vibe-Testing

This snippet indicates the file path for the complete step-by-step instructions, including prompt templates and decision trees, used by the Cursor agent.

```text
/Users/joeyfarina/code/xds/vibe-test-runs/GUIDE.md
```

--------------------------------

### StyleX Animation Example

Source: https://github.com/facebook/astryx/wiki/Animation-System

Demonstrates how to implement enter animations using StyleX and CSS transitions. This approach leverages `@starting-style` for initial states and CSS transitions for smooth property changes. Ensure browser compatibility for `@starting-style`.

```tsx
import * as stylex from '@stylexjs/stylex';
import { motionTokens } from '@xds/theme';

const styles = stylex.create({
  dialog: {
    opacity: 1,
    transform: 'scale(1)',
    transition: `opacity ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}, transform ${motionTokens.durationNormal} ${motionTokens.easingEaseOut}`,
  },
});
```

--------------------------------

### Night Watch QA - Bad Example: CI Diagnosis

Source: https://github.com/facebook/astryx/wiki/Night-Watch-QA

Example of an ineffective review comment from an auto-managed Dependabot PR, diagnosing a CI issue that did not change the outcome.

```text
🤖 Night Watch QA — CI Diagnosis
The test check is failing with a performance regression...
```

--------------------------------

### Get Full Astryx Component Documentation via CLI

Source: https://github.com/facebook/astryx/wiki/System-Architecture

Retrieve comprehensive documentation for a specific component, such as 'Button', using the CLI. This is useful for detailed AI understanding.

```bash
npx xds component Button
```