# Primer React Copilot Instructions

**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.**

## Repository Organization

The project is the React implementation of GitHub's Primer Design System authored as a monorepo with separate npm workspaces.
The primary workspace is `packages/react` which contains the `@primer/react` package that distributes React components for the design system.

**Key Directory Structure:**

- `e2e/`: End-to-end tests running Visual Regression Tests (@vrt) and Accessibility Verification Tests (@avt) using Playwright
- `examples/`: Example applications (nextjs, theming, codesandbox) demonstrating design system usage
- `packages/react/`: Primary package containing all React components and main development workspace
- `packages/mcp/`: Model Context Protocol server for AI tools integration
- `packages/styled-react/`: Legacy styled-components package (being migrated from)
- `script/`: Repository-wide build and utility scripts
- `contributor-docs/`: Contributing guidelines, testing docs, and Architecture Decision Records (ADRs)

## Working Effectively

**Bootstrap and build the repository:**

- Dependencies: Node.js (check with `node --version`), npm (check with `npm --version`)
- `npm install` -- installs dependencies. ~5 seconds with cache, ~2 minutes for clean install. Set timeout to 180+ seconds.
- `npm run build` -- builds all packages. NEVER CANCEL. Takes 90 seconds without turbo cache, ~1 second with cache. Set timeout to 120+ minutes.
- `npx turbo run build` -- builds all packages including example applications. Takes ~33 seconds.

**Node.js version updates:**

- When updating Node.js, update `.nvmrc` and `.devcontainer/devcontainer.json` together. Also check contributor documentation for any hardcoded Node.js version guidance, such as `contributor-docs/CONTRIBUTING.md`.
- GitHub Actions workflows use `node-version-file: '.nvmrc'`; only update workflow files if they stop using `.nvmrc`.

**Run tests:**

- `npm test` -- runs unit tests. NEVER CANCEL. Takes 75 seconds. Set timeout to 90+ minutes. Runs 1500+ tests using Vitest in both node and chromium environments.
- Vitest console enforcement is enabled by default in CI. For local debugging, it is disabled unless you opt in with `VITEST_FAIL_ON_CONSOLE=true npm test`.
- `npm run type-check` -- runs TypeScript type checking across all packages. Takes 42 seconds. Set timeout to 60+ minutes.

**Development workflow:**

- Main component development happens in `packages/react/src/[ComponentName]/`

**Turbo usage in this repository:**

- This repository uses Turborepo for selected workspace orchestration, not for every validation command. Follow the existing root npm scripts first unless you are specifically changing Turbo configuration.
- `npm run build` delegates to `turbo run build --filter='!./examples/*'`, so it builds workspace packages while excluding examples. Use `npx turbo run build` when you intentionally need Turbo's direct CLI behavior, such as building all workspaces including examples.
- `npm run type-check` runs the root TypeScript check first, then `turbo run type-check` for packages that define that task.
- `npm test`, `npm run lint`, `npm run lint:css`, `npm run format`, and `npm run format:diff` are not currently Turbo-orchestrated. Do not replace them with Turbo commands unless you are intentionally updating the repository's task setup.
- Use the `turborepo` skill when creating or changing `turbo.json`, package task scripts that should be orchestrated by Turbo, caching/outputs/env behavior, CI Turbo usage, filters such as `--affected` or `--filter`, or debugging Turbo cache/task execution. For ordinary Primer React component work, validation, or package scripts that already exist, use the commands documented here instead of applying generic Turborepo guidance.

**Linting and formatting:**

- `npm run lint` -- lints JavaScript/TypeScript/Markdown. Takes 73 seconds.
- `npm run lint:fix` -- auto-fixes linting issues where possible
- `npm run lint:css` -- lints CSS files using Stylelint. Takes 6 seconds.
- `npm run lint:css:fix` -- auto-fixes CSS linting issues
- `npm run format` -- formats code using Prettier
- `npm run format:diff` -- checks for unformatted files. Takes 2 seconds.

## Validation Scenarios

**Always validate your changes by:**

1. Building the project: `npm run build` (ensures TypeScript compilation succeeds)
2. Running unit tests: `npm test` (ensures component behavior works correctly)
3. Type checking: `npm run type-check` (ensures TypeScript types are correct)
4. Linting: `npm run lint` and `npm run lint:css` (ensures code style compliance)
5. Formatting: `npm run format:diff` (ensures consistent code formatting)

**For component changes:**

1. Start Storybook: `npm start`
2. Navigate to your component story to visually verify changes
3. Run accessibility tests: `script/test-e2e --grep @avt` if accessibility is impacted
4. Run visual regression tests: `script/test-e2e --grep @vrt` if visual appearance changed

**Before committing:**

- Always run `npm run format` before committing or CI will fail
- Run `npm run lint:fix` to auto-fix linting issues
- Ensure `npm run build` succeeds without errors

## Component Development Guide

**File Structure (packages/react/src/):**
Components follow this pattern:

```
ComponentName/
├── index.ts              // Re-exports
├── ComponentName.tsx     // Main component
├── ComponentName.stories.tsx  // Storybook stories
├── ComponentName.features.stories.tsx  // (optional) Storybook feature stories
├── ComponentName.test.tsx     // Unit tests
├── ComponentName.docs.json    // Documentation metadata
└── __snapshots__/        // Test snapshots (being migrated to VRT)
```

**Common File Patterns:**

- `*.module.css` -- CSS Modules for component styling
- `*.test.tsx` -- Unit tests using Vitest and Testing Library
- `[ComponentName].stories.tsx` -- Default Storybook stories for documentation and testing
- `[ComponentName].features.stories.tsx` -- Storybook feature stories
- `*.docs.json` -- Component metadata for documentation generation

## CI/CD and Workflows

**Key GitHub Actions:**

- `.github/workflows/ci.yml` -- Main CI pipeline (format, lint, test, type-check, build)
- `.github/workflows/vrt.yml` -- Visual regression testing

**The CI will fail if:**

- Code is not formatted (`npm run format` fixes this)
- Linting errors exist (`npm run lint:fix` auto-fixes many)
- TypeScript compilation fails
- Unit tests fail
- Build fails

## Quick Start Commands Summary

For agents working on this repository for the first time:

```bash
# 1. Check prerequisites
node --version
npm --version

# 2. Install and build (NEVER CANCEL - takes ~2-3 minutes total)
npm install     # ~5 seconds (or ~2 minutes clean)
npm run build   # ~90 seconds without cache

# 3. Start development
npm start       # Starts Storybook on http://localhost:6006

# 4. Run tests and checks
npm test                # ~75 seconds - unit tests
npm run type-check      # ~42 seconds - TypeScript validation
npm run lint            # ~73 seconds - code linting
npm run format:diff     # ~2 seconds - format checking

# 5. Before committing
npm run format          # Fix formatting
npm run lint:fix        # Auto-fix linting issues
```

## Storybook

When working on UI components, always use the `primer-storybook` MCP tools to access Storybook's component and documentation knowledge before answering or taking any action. Reference the `.github/skills/storybook/SKILL.md` file for detailed instructions on using the Storybook MCP effectively and accurately.

**Story conventions:**

- Each component should have a default stories file colocated with the component (for most components: `packages/react/src/[ComponentName]/[ComponentName].stories.tsx`).
- The default stories file should use the `Components/[ComponentName]` Storybook title and include `Default` and `Playground` stories when the component supports configurable controls.
- Put feature-specific stories colocated with the component (for most components: `packages/react/src/[ComponentName]/[ComponentName].features.stories.tsx`) with the `Components/[ComponentName]/Features` Storybook title.
- Keep examples or scenario-based stories in separate files, such as `[ComponentName].examples.stories.tsx`, when they are distinct from core feature coverage

## Slots

When building, modifying, or wrapping compound components that use child-component "slots" (anything involving `__SLOT__`, `useSlots`, `isSlot`, or `asSlot`), reference the `.github/skills/slots/SKILL.md` file. It documents when to add slot markers, naming conventions for `Symbol(...)` descriptions, the public slot APIs, and common pitfalls.

## Known Issues and Workarounds

**Timing Expectations:**

- Fresh install: ~5 seconds (clean install: ~2 minutes)
- Full clean build: ~90 seconds (with turbo cache: ~1 second)
- Build all including examples: ~33 seconds
- Unit tests: ~75 seconds
- Type checking: ~42 seconds
- Linting: ~73 seconds
- CSS linting: ~6 seconds
- Format checking: ~2 seconds
- Storybook startup: ~3 seconds

**CRITICAL**: NEVER CANCEL builds, tests, or long-running commands. They may take significantly longer in CI environments. Always set appropriate timeouts (90+ minutes for builds/tests).

## Pull Request Creation

When creating a pull request, you MUST:

1. Use the template in `.github/pull_request_template.md` to structure the PR description. Read the template file, fill in all sections appropriately, and include it in the PR body.
2. Include a changeset file in the PR if the change affects the published package (bug fix, new feature, breaking change, etc.). Create a `.changeset/<descriptive-name>.md` file with the appropriate semver bump type. Reference the `changesets` skill (`.github/skills/changesets/SKILL.md`) for detailed guidance on file format, choosing the correct bump type, and when a changeset can be skipped.
3. If no changeset is needed (docs-only, test-only, CI/infra changes), add the `skip changeset` label to the pull request to bypass the CI changeset check.