### Setup Primer React Environment

Source: https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md

Run this command to set up your local environment for developing Primer React components. Ensure Node.js v20 is installed.

```sh
npm run setup
```

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

### Install Primer React

Source: https://context7.com/primer/react/llms.txt

Commands to install the library using npm or yarn.

```bash
npm install @primer/react

# or with yarn
yarn add @primer/react
```

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

### Install postcss-preset-primer

Source: https://github.com/primer/react/blob/main/packages/postcss-preset-primer/README.md

Install the package as a development dependency using npm.

```bash
npm install postcss-preset-primer --save-dev
```

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

### Install Primer React dependencies

Source: https://github.com/primer/react/blob/main/packages/react/README.md

Commands to install the required packages using npm or Yarn.

```bash
npm install -S @primer/react @primer/primitives
```

```bash
yarn add @primer/react @primer/primitives
```

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

### Install @primer/styled-react

Source: https://github.com/primer/react/blob/main/packages/styled-react/README.md

Use npm to add the package as a dependency to your project.

```bash
npm install -S @primer/styled-react
```

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

### Install Primer React

Source: https://github.com/primer/react/blob/main/README.md

Use these commands to add the @primer/react package to your project dependencies.

```console
npm install @primer/react
```

```console
yarn add @primer/react
```

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

### Install Dependencies in Docs Folder

Source: https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md

Ensure dependencies are installed in both the root and the docs subfolder to avoid 'gatsby: command not found' errors.

```bash
npm install
```

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

### Example plugin output

Source: https://github.com/primer/react/blob/main/packages/rollup-plugin-import-css/README.md

The resulting import structure after the plugin processes the CSS modules.

```ts
// Example output
import './path-to-header-[hash].css'
export default {
  header: 'header___3s4s',
}
```

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

### Start Storybook for Primer React Development

Source: https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md

Use this command to launch the Storybook environment for developing and previewing Primer React components locally. Access it at http://localhost:6006/.

```sh
npm start
```

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

### Install Playwright Dependencies

Source: https://github.com/primer/react/blob/main/contributor-docs/testing.md

Install Playwright and its browser dependencies. Required before running Playwright tests locally.

```bash
npx playwright install --with-deps
```

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

### Basic vs. Responsive Value Example

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-018-responsive-values.md

Illustrates the difference between a standard prop value and a responsive prop value in a component.

```tsx
// Value
<Stack gap="condensed" />

// Responsive value
<Stack gap={{ narrow: 'condensed', regular: 'normal', wide: 'spacious' />
```

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

### Start Storybook for Accessibility Testing

Source: https://github.com/primer/react/blob/main/contributor-docs/testing.md

Command to launch Storybook with the environment variable required for accessibility verification.

```bash
STORYBOOK=true npx start-storybook -p 6006
```

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

### Usage Example of Responsive Padding in Stack Component

Source: https://github.com/primer/react/blob/main/contributor-docs/authoring-css.md

Demonstrates how to use the responsive padding prop by passing an object with different values for different viewport sizes.

```tsx
// usage
<Stack padding={{narrow: 'none', regular: 'normal'}} />
```

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

### Node.js Package Exports Example

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-015-internal-modules.md

An example from Node.js documentation showing how to define package exports, including a pattern to exclude internal files.

```json
{
  "name": "my-package",
  "exports": {
    ".": "./lib/index.js",
    "./feature/*.js": "./feature/*.js",
    "./feature/internal/*": null
  }
}
```

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

### Import and use a component

Source: https://github.com/primer/react/blob/main/packages/react/README.md

Basic example of importing a component from the package and rendering it in a React function.

```tsx
import {Button} from '@primer/react'

function App() {
  return <Button>Hello world</Button>
}
```

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

### Implement Tabs with Utility Hooks

Source: https://github.com/primer/react/blob/main/packages/react/src/experimental/Tabs/README.mdx

Demonstrates how to use the `Tabs`, `useTabList`, `useTab`, and `useTabPanel` hooks to build a custom tabbed interface. This example shows the basic structure for creating tab buttons and their corresponding content panels.

```tsx
import React from 'react'
import {Tabs, useTabList, useTab, useTabPanel} from '@primer/react/experimental'

function TabPanel({children, ...props}) {
  const tabPanelProps = useTabPanel(props)
  return <div {...tabPanelProps}>{children}</div>
}

function Tab({children, ...props}) {
  const tabProps = useTab(props)
  return <button {...tabProps}>{children}</button>
}

function TabList({children, ...props}) {
  const tabListProps = useTabList(props)
  return <div {...tabListProps}>{children}</div>
}

export function MyTabs() {
  return (
    <Tabs defaultValue="tab1">
      <TabList>
        <Tab value="tab1">Tab 1</Tab>
        <Tab value="tab2">Tab 2</Tab>
      </TabList>
      <TabPanel value="tab1">
        <p>This is the content for Tab 1.</p>
      </TabPanel>
      <TabPanel value="tab2">
        <p>This is the content for Tab 2.</p>
      </TabPanel>
    </Tabs>
  )
}
```

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

### npm Package Exports Configuration (Example)

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-015-internal-modules.md

This JSON configuration snippet illustrates how to define export patterns for an npm package, specifically showing how to include and exclude modules.

```json
{
  exports: {
    // ...
    './lib-esm/*': {
      import: [
        // ...
      ],
      require: [
        // ...
      ],
    },
  },
}
```

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

### Basic Primer React Component Structure

Source: https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md

Example of a basic component file in Primer React, demonstrating imports, props, and component rendering. Ensure to include `SxProp` for styling capabilities.

```tsx
import type React from 'react'
import styles from './Component.module.css'
import {clsx} from 'clsx'

export type ComponentProps = {
  prop?: 'value1' | 'value2'
  className?: string
} & SxProp

const Component: React.FC<React.PropsWithChildren<ComponentProps>> = ({
  prop = 'value1',
  children,
  className,
  ...props
}) => {
  return (
    <nav className={clsx(className, styles.Nav)} {...props}>
      {children}
    </nav>
  )
}

Component.displayName = 'Component'

export default Component
```

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

### Define props in .docs.json

Source: https://github.com/primer/react/blob/main/packages/doc-gen/README.md

Example of a manually defined property in a component's documentation file.

```json
{
  "props": [
    {
      "name": "alignContent",
      "type": "'start' | 'center'",
      "default": "start",
      "description": "Content alignment for when visuals are present.",
      "required": false
    }
  ]
}
```

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

### Flash with custom styling and dismiss button

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

Example of extending Flash functionality by using `sx` prop for custom layout and adding a dismiss button.

```jsx
<Flash variant="success" sx={{display: 'flex', justifyContent: 'space-between'}}>
  <span>
    <CheckIcon /> Changes saved!
  </span>
  <Button variant="invisible" icon={CheckIcon} aria-label="Hide flash message" onClick={onDismiss} />
</Flash>
```

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

### SSR Runtime Setup for Custom Elements

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-009-behavior-isolation.md

These lines are necessary to load a custom element into a server-side runtime like NodeJS. Add these to the custom element's code.

```typescript
const root = (typeof globalThis !== 'undefined' ? globalThis : window) as typeof window
const HTMLElement = root.HTMLElement || (null as unknown as (typeof window)['HTMLElement'])
```

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

### Standard HTML element patterns

Source: https://github.com/primer/react/blob/main/contributor-docs/component-contents-api-patterns.md

Examples of standard HTML elements that use children to define their structure.

```jsx
<div>
  <div>Some content</div>
  <div>More content</div>
</div>
```

```jsx
<ul>
  <li>Item 1</li>
  <li>Item 2</li>
</ul>
```

```jsx
<select>
  <option value="1">First option</option>
  <option value="1">Second option</option>
</select>
```

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

### Example of ShadowDOM in an Input Element

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-009-behavior-isolation.md

Illustrates the internal ShadowDOM structure of an HTML input element as rendered in Chrome. This shows how built-in elements use ShadowDOM for encapsulation.

```html
<div pseudo="-webkit-onput-placeholder" id="placeholder" style="display: none !important">Placeholder content</div>
<div>input contents</div>
```

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

### Banner Component Examples

Source: https://context7.com/primer/react/llms.txt

Demonstrates various banner variants including info, warning, critical, and success messages. Each banner can have a title, description, and actions.

```tsx
import {Banner} from '@primer/react'

function BannerExamples() {
  return (
    <div style={{display: 'flex', flexDirection: 'column', gap: '12px'}}>
      {/* Info banner */}
      <Banner
        title="New feature available"
        description="Check out our new collaboration tools."
        variant="info"
        onDismiss={() => console.log('Dismissed')}
      />

      {/* Warning banner */}
      <Banner
        title="Approaching storage limit"
        description="You have used 90% of your storage quota."
        variant="warning"
      />

      {/* Critical banner */}
      <Banner
        title="Action required"
        description="Your billing information needs to be updated."
        variant="critical"
        primaryAction={{
          text: 'Update billing',
          onClick: () => console.log('Update clicked')
        }}
        secondaryAction={{
          text: 'Learn more',
          onClick: () => console.log('Learn more clicked')
        }}
      />

      {/* Success banner */}
      <Banner
        title="Changes saved"
        description="Your repository settings have been updated successfully."
        variant="success"
      />
    </div>
  )
}
```

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

### Managing Focus Trap Lifecycle in Primer View Components

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-009-behavior-isolation.md

This example shows how to manage the lifecycle of a focus trap using an AbortController in a View Component. It highlights that a component is still required to manage the focus trap's attachment.

```ruby
class MyComponent < Primer::ViewComponent
  def initialize
    @abort_controller = AbortController.new
  end

  def call
    # ...
    focus_trap(container: @container, initial_focus: @initial_focus, signal: @abort_controller.signal)
    # ...
  end

  private

  def focus_trap(container:, initial_focus:, signal:)
    # Implementation details for focus trap
  end
end
```

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

### Basic Dialog Example - Primer React

Source: https://context7.com/primer/react/llms.txt

Use this Dialog component for modal overlays requiring user confirmation or focused interaction. It handles focus trapping and escape key dismissal. Ensure to manage the 'isOpen' state to control visibility.

```tsx
import {Dialog, Button} from '@primer/react'

function DialogExample() {
  const [isOpen, setIsOpen] = React.useState(false)

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Dialog</Button>

      {isOpen && (
        <Dialog
          title="Confirm action"
          subtitle="This action cannot be undone"
          onClose={(gesture) => {
            console.log('Dialog closed via:', gesture) // 'close-button' or 'escape'
            setIsOpen(false)
          }}
          footerButtons={[
            {
              content: 'Cancel',
              onClick: () => setIsOpen(false)
            },
            {
              content: 'Confirm',
              buttonType: 'danger',
              onClick: () => {
                console.log('Confirmed!')
                setIsOpen(false)
              },
              autoFocus: true
            }
          ]}>
          <p>Are you sure you want to delete this repository? All data will be permanently removed.</p>
        </Dialog>
      )}
    </>
  )
}
```

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

### Flash component with icon and explicit styling in children

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

This example shows how developers can still pass an icon as a child with specific styling, but it requires more explicit configuration, highlighting the increased effort for non-standard usage.

```jsx
<Flash variant="success">
  <CheckIcon size={20} color="success.emphasis" sx={{marginRight: 2}} />
  Changes saved!
</Flash>
```

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

### Run v1.0.0-beta codemod

Source: https://github.com/primer/react/blob/main/migrating.md

Use this command to upgrade from 0.x.x-beta versions.

```bash
npx jscodeshift -t node_modules/primer-react/codemods/v1.js path/to/src
```

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

### HTML button markup

Source: https://github.com/primer/react/blob/main/contributor-docs/versioning.md

Example of markup where whitespace between elements is significant for layout.

```html
<button type="button" class="custom-button">Save <span class="custom-class">changes</span></button>
```

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

### Implement ActionList with selection and grouping

Source: https://context7.com/primer/react/llms.txt

Shows how to build a list with multiple selection, dividers, group headings, and navigation links.

```tsx
import {ActionList} from '@primer/react'
import {FileIcon, FolderIcon, StarIcon, CheckIcon} from '@primer/octicons-react'

function ActionListExample() {
  const [selected, setSelected] = React.useState<string[]>([])

  const toggleSelection = (item: string) => {
    setSelected(prev =>
      prev.includes(item)
        ? prev.filter(i => i !== item)
        : [...prev, item]
    )
  }

  return (
    <ActionList selectionVariant="multiple" showDividers>
      <ActionList.Heading>Recent files</ActionList.Heading>

      <ActionList.Group>
        <ActionList.GroupHeading>Documents</ActionList.GroupHeading>
        <ActionList.Item
          selected={selected.includes('readme')}
          onSelect={() => toggleSelection('readme')}
        >
          <ActionList.LeadingVisual><FileIcon /></ActionList.LeadingVisual>
          README.md
          <ActionList.TrailingVisual>12kb</ActionList.TrailingVisual>
        </ActionList.Item>
        <ActionList.Item
          selected={selected.includes('package')}
          onSelect={() => toggleSelection('package')}
        >
          <ActionList.LeadingVisual><FileIcon /></ActionList.LeadingVisual>
          package.json
          <ActionList.Description>Configuration file</ActionList.Description>
        </ActionList.Item>
      </ActionList.Group>

      <ActionList.Divider />

      <ActionList.Group>
        <ActionList.GroupHeading>Folders</ActionList.GroupHeading>
        <ActionList.Item>
          <ActionList.LeadingVisual><FolderIcon /></ActionList.LeadingVisual>
          src
        </ActionList.Item>
      </ActionList.Group>

      {/* Link items navigate instead of triggering actions */}
      <ActionList.LinkItem href="/starred">
        <ActionList.LeadingVisual><StarIcon /></ActionList.LeadingVisual>
        View starred items
      </ActionList.LinkItem>
    </ActionList>
  )
}
```

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

### Run v3.0.0-beta codemod

Source: https://github.com/primer/react/blob/main/migrating.md

Use this command to upgrade from v2.x.x-beta and update the package name to @primer/components.

```bash
npx jscodeshift -t node_modules/@primer/components/codemods/v3.js path/to/src
```

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

### Inline Event Handler Usage

Source: https://github.com/primer/react/blob/main/contributor-docs/versioning.md

Example of an inline event handler where the type is inferred automatically.

```tsx
function ExampleComponent() {
  return (
    <Item
      onSelect={event => {
        //
      }}
    />
  )
}
```

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

### Configure RootLayout with BaseStyles

Source: https://github.com/primer/react/blob/main/packages/react/README.md

Wrap the application in BaseStyles and import the necessary CSS theme files.

```tsx
// Import each of the themes you would like to use, by default we are including
// the light theme below
import '@primer/primitives/dist/css/functional/themes/light.css'
import {BaseStyles} from '@primer/react'

function RootLayout() {
  return (
    <BaseStyles>
      <App />
    </BaseStyles>
  )
}
```

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

### ActionList Component Structure

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

Example of using composite children within an ActionList to manage list items and their descriptions.

```jsx
<ActionList showDividers>
  <ActionList.Item>
    <ActionList.LeadingVisual><Avatar src=""/></ActionList.LeadingVisual>
    mona
    <ActionList.Description>Monalisa Octocat</ActionList.Description>
  <ActionList.Item>
  <ActionList.Item>
    <ActionList.LeadingVisual><Avatar src=""/></ActionList.LeadingVisual>
    primer-css
    <ActionList.Description variant="block">GitHub</ActionList.Description>
  <ActionList.Item>
</ActionList>
```

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

### Run v2.0.0-beta codemod

Source: https://github.com/primer/react/blob/main/migrating.md

Use this command to upgrade from v1.x.x-beta. Ensure component renames are handled in the specified order to avoid conflicts.

```bash
npx jscodeshift -t node_modules/primer-react/codemods/v2.js path/to/src
```

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

### Increase component selector specificity

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-021-css-layers.md

Example of a version update that breaks existing override styles due to increased specificity.

```css
/* v1.1.0 of a component */
.Component[data-variant='default'] {
  color: var(--fgColor-default);
}
```

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

### Migrating ActionList Group Title API

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-019-deprecating-props.md

Example showing the transition from a deprecated title prop to the new ActionList.GroupHeading component.

```tsx
// old API
<ActionList>
  <ActionList.Group title="Group title">
    <ActionList.Item>Item 1</ActionList.Item>
    <ActionList.Item>Item 2</ActionList.Item>
  </ActionList.Group>
</ActionList>
```

```tsx
// new API
<ActionList>
  <ActionList.Group>
    <ActionList.GroupHeading as="h2">Group title</ActionList.GroupHeading>
    <ActionList.Item>Item 1</ActionList.Item>
    <ActionList.Item>Item 2</ActionList.Item>
  </ActionList.Group>
</ActionList>
```

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

### Configure postcss-preset-primer

Source: https://github.com/primer/react/blob/main/packages/postcss-preset-primer/README.md

Import and register the plugin within your postcss.config.js file.

```javascript
// postcss.config.js
const postcssPresetPrimer = require('postcss-preset-primer')

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: [postcssPresetPrimer()],
}

module.exports = config
```

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

### Extracted Event Handler with Explicit Typing

Source: https://github.com/primer/react/blob/main/contributor-docs/versioning.md

Example of an extracted event handler function with an explicit React event type definition.

```tsx
function ExampleComponent() {
  function onSelect(event: React.MouseEvent<HTMLDivElement>) {
    //
  }

  return <Item onSelect={onSelect} />
}
```

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

### Implement Button variants and configurations

Source: https://context7.com/primer/react/llms.txt

Demonstrates various button styles, sizes, icon integration, loading states, and the IconButton component.

```tsx
import {Button, IconButton} from '@primer/react'
import {PlusIcon, SearchIcon, TrashIcon} from '@primer/octicons-react'

function ButtonExamples() {
  return (
    <div style={{display: 'flex', gap: '8px', flexWrap: 'wrap'}}>
      {/* Basic variants */}
      <Button>Default</Button>
      <Button variant="primary">Primary</Button>
      <Button variant="danger">Danger</Button>
      <Button variant="invisible">Invisible</Button>
      <Button variant="link">Link style</Button>

      {/* With icons */}
      <Button leadingVisual={PlusIcon}>Create new</Button>
      <Button trailingVisual={SearchIcon}>Search</Button>

      {/* Sizes */}
      <Button size="small">Small</Button>
      <Button size="medium">Medium</Button>
      <Button size="large">Large</Button>

      {/* Loading state */}
      <Button loading loadingAnnouncement="Saving changes">
        Save
      </Button>

      {/* Block (full width) */}
      <Button block>Full Width Button</Button>

      {/* Icon-only button with tooltip */}
      <IconButton icon={TrashIcon} aria-label="Delete item" variant="danger" />
      <IconButton
        icon={SearchIcon}
        aria-label="Search"
        description="Search the repository"
        keybindingHint="Mod+K"
      />
    </div>
  )
}
```

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

### Project Structure with NPM Workspaces

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-014-npm-workspaces.md

This illustrates the proposed directory layout for the primer/react project after implementing NPM workspaces. It shows the placement of the root package.json and various child workspaces.

```tree
- root
  # Root package.json, defines workspaces
  - package.json

  # Workspaces
  - docs
  - packages
    - react
    - *
  - examples
    - nextjs
    - consumer-test
    - *

  # Top-level scripts
  - script

  # Testing & Development
  - .storybook
  - .playwright

  # Repo config
  - .github
  - .vscode

```

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

### Importing default and draft components

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-010-drafts-are-experimental.md

Demonstrates how to import the default version of a component from the root of the package versus a new version from the /drafts directory.

```javascript
// default version of component exported from root of package
import {UnderlineNav} from '@primer/react'

// new version of component exported from /drafts
import {UnderlineNav} from '@primer/react/drafts'
```

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

### Configure ThemeProvider and useTheme

Source: https://context7.com/primer/react/llms.txt

Wraps the application to provide theming context and demonstrates accessing theme state with the useTheme hook.

```tsx
import {ThemeProvider, BaseStyles, Button} from '@primer/react'

function App() {
  return (
    <ThemeProvider colorMode="auto" dayScheme="light" nightScheme="dark">
      <BaseStyles>
        <Button variant="primary">Hello Primer</Button>
      </BaseStyles>
    </ThemeProvider>
  )
}

// Using the useTheme hook to access theme context
import {useTheme} from '@primer/react'

function ThemeAwareComponent() {
  const {colorMode, setColorMode, resolvedColorScheme} = useTheme()

  return (
    <div>
      <p>Current color scheme: {resolvedColorScheme}</p>
      <button onClick={() => setColorMode('dark')}>Switch to Dark</button>
      <button onClick={() => setColorMode('light')}>Switch to Light</button>
      <button onClick={() => setColorMode('auto')}>Use System Preference</button>
    </div>
  )
}
```

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

### Switching import path from drafts to experimental

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-010-drafts-are-experimental.md

Illustrates the code change required to switch from importing a component via the /drafts path to the new /experimental path.

```diff
// new version of component exported from /experimental
- import { UnderlineNav } from '@primer/react/drafts'
+ import { UnderlineNav } from '@primer/react/experimental'
```

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

### Run v4.0.0-beta codemod

Source: https://github.com/primer/react/blob/main/migrating.md

Use this command to automatically upgrade component identifiers from v3.x.x-beta to v4.0.0-beta.

```bash
npx jscodeshift -t node_modules/@primer/components/codemods/v4.js path/to/src
```

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

### Arrange elements with Stack

Source: https://context7.com/primer/react/llms.txt

Demonstrates horizontal, vertical, and responsive layouts using the Stack primitive with configurable gaps and alignment.

```tsx
import {Stack, Button, Avatar, Text} from '@primer/react'

function StackExamples() {
  return (
    <>
      {/* Horizontal stack with gap */}
      <Stack direction="horizontal" gap="normal" align="center">
        <Avatar src="https://github.com/octocat.png" size={32} />
        <Text>octocat</Text>
        <Button size="small">Follow</Button>
      </Stack>

      {/* Vertical stack */}
      <Stack direction="vertical" gap="condensed">
        <Text fontWeight="bold">Repository name</Text>
        <Text color="fg.muted">A description of the repository</Text>
      </Stack>

      {/* Responsive direction */}
      <Stack
        direction={{narrow: 'vertical', regular: 'horizontal'}}
        gap="normal"
        padding="normal"
      >
        <Stack.Item grow>Main content area</Stack.Item>
        <Stack.Item>Sidebar</Stack.Item>
      </Stack>

      {/* With wrap and justify */}
      <Stack direction="horizontal" wrap="wrap" justify="space-between">
        <Button>Action 1</Button>
        <Button>Action 2</Button>
        <Button>Action 3</Button>
      </Stack>
    </>
  )
}
```

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

### Run Unit Tests

Source: https://github.com/primer/react/blob/main/contributor-docs/testing.md

Execute all unit tests for the project. Use this to ensure code quality and catch regressions.

```bash
npm test
```

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

### Unpreferred: Snapshot Test for Component Rendering

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-011-snapshot-tests.md

This is an example of an unpreferred snapshot test for a React component. It captures the entire render tree, which can lead to large snapshots and difficulty in debugging changes.

```tsx
it('renders correctly', () => {
  const tree = renderer.create(<Link page="http://www.github.com">GitHub</Link>).toJSON()
  expect(tree).toMatchSnapshot()
})
```

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

### Dialog Component Behavior Hook Example

Source: https://github.com/primer/react/blob/main/contributor-docs/behaviors.md

Illustrates the expected return value structure for a component behavior hook like `usePopover`. The returned object contains props intended to be spread onto specific JSX elements.

```javascript
{
  popoverProps: PropsObject,
  openClickTargetProps: PropsObject,
  closeClickTargetProps: PropsObject
}
```

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

### Implement ActionMenu with items and controlled state

Source: https://context7.com/primer/react/llms.txt

Demonstrates standard ActionMenu usage with icons and descriptions, alongside a controlled state implementation.

```tsx
import {ActionMenu, ActionList} from '@primer/react'
import {GearIcon, CopyIcon, PencilIcon, TrashIcon} from '@primer/octicons-react'

function ActionMenuExample() {
  const [selectedOption, setSelectedOption] = React.useState('option1')

  return (
    <ActionMenu>
      <ActionMenu.Button>Actions</ActionMenu.Button>
      <ActionMenu.Overlay>
        <ActionList>
          <ActionList.Item onSelect={() => console.log('Copy clicked')}>
            <ActionList.LeadingVisual><CopyIcon /></ActionList.LeadingVisual>
            Copy link
          </ActionList.Item>
          <ActionList.Item onSelect={() => console.log('Edit clicked')}>
            <ActionList.LeadingVisual><PencilIcon /></ActionList.LeadingVisual>
            Edit
            <ActionList.Description variant="block">
              Modify this item's content
            </ActionList.Description>
          </ActionList.Item>
          <ActionList.Divider />
          <ActionList.Item variant="danger" onSelect={() => console.log('Delete clicked')}>
            <ActionList.LeadingVisual><TrashIcon /></ActionList.LeadingVisual>
            Delete
          </ActionList.Item>
        </ActionList>
      </ActionMenu.Overlay>
    </ActionMenu>
  )
}

// With controlled open state
function ControlledActionMenu() {
  const [open, setOpen] = React.useState(false)

  return (
    <ActionMenu open={open} onOpenChange={setOpen}>
      <ActionMenu.Button>Menu ({open ? 'open' : 'closed'})</ActionMenu.Button>
      <ActionMenu.Overlay>
        <ActionList>
          <ActionList.Item onSelect={() => setOpen(false)}>Option 1</ActionList.Item>
          <ActionList.Item onSelect={() => setOpen(false)}>Option 2</ActionList.Item>
        </ActionList>
      </ActionMenu.Overlay>
    </ActionMenu>
  )
}
```

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

### Form Control with Input, Select, Textarea, and Checkbox - Primer React

Source: https://context7.com/primer/react/llms.txt

Utilize FormControl to structure form elements, providing labels, captions, and validation messages. This example demonstrates integrating TextInput with validation, a Select dropdown, a Textarea with a character limit hint, and a horizontally laid out Checkbox.

```tsx
import {FormControl, TextInput, Select, Checkbox, Textarea} from '@primer/react'

function FormExample() {
  const [username, setUsername] = React.useState('')
  const [hasError, setHasError] = React.useState(false)

  return (
    <form style={{display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '400px'}}>
      {/* Text input with validation */}
      <FormControl required>
        <FormControl.Label>Username</FormControl.Label>
        <TextInput
          value={username}
          onChange={(e) => setUsername(e.target.value)}
          validationStatus={hasError ? 'error' : undefined} />
        <FormControl.Caption>Enter your unique username</FormControl.Caption>
        {hasError && (
          <FormControl.Validation variant="error">
            Username is already taken
          </FormControl.Validation>
        )}
      </FormControl>

      {/* Select dropdown */}
      <FormControl>
        <FormControl.Label>Visibility</FormControl.Label>
        <Select>
          <Select.Option value="public">Public</Select.Option>
          <Select.Option value="private">Private</Select.Option>
          <Select.Option value="internal">Internal</Select.Option>
        </Select>
      </FormControl>

      {/* Textarea with character limit */}
      <FormControl>
        <FormControl.Label>Description</FormControl.Label>
        <Textarea placeholder="Describe your project..." />
        <FormControl.Caption>Optional project description</FormControl.Caption>
      </FormControl>

      {/* Checkbox with horizontal layout */}
      <FormControl layout="horizontal">
        <Checkbox />
        <FormControl.Label>I agree to the terms of service</FormControl.Label>
      </FormControl>
    </form>
  )
}
```

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

### Define CSS layers with namespace

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-022-css-layer-names.md

Use the primer namespace for all layers, applying camelCase for general layers and PascalCase for specific components.

```css
@layer primer.base {
  /* ... */
}

@layer primer.components.Button {
  /* ... */
}
```

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

### Component Directory Structure

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-013-file-structure.md

The recommended file layout for a component within the src directory, including source files, tests, and documentation.

```text
primer-react/
├─ src/
│  ├─ Breadcrumbs/
│  │  ├─ index.ts                    // Just re-exporting?
│  │  ├─ Breadcrumbs.tsx             // Primary component
│  │  ├─ BreadcrumbsItem.tsx         // Subcomponent (include parent component name to increase findability in most IDEs)
│  │  ├─ Breadcrumbs.mdx             // Documentation. Always .mdx, not .md
│  │  ├─ Breadcrumbs.stories.tsx
│  │  ├─ Breadcrumbs.test.tsx        // Unit tests
│  │  ├─ Breadcrumbs.types.test.tsx  // Type tests
│  │  ├─ Breadcrumbs.yml             // Component metadata (Possible future)
│  │  └─ __snapshots__/
┆  ┆
```

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

### Stack Component with Responsive Gap Prop

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-018-responsive-values.md

Demonstrates how to define a responsive prop for a component and use a helper function to generate corresponding data attributes for CSS styling. This approach prevents layout shifts during SSR.

```tsx
type GapScale = 'none' | 'condensed' | 'normal' | 'spacious'

type StackProps = React.PropsWithChildren<{
  // Responsive props should be a union of the value of the prop plus
  // `ResponsiveValue` over that value
  gap?: GapScale | ResponsiveValue<GapScale>
}>

function Stack({children, gap}: StackProps) {
  // The `getResponsiveAttributes` helper is useful for adding the corresponding
  // `data-*` attributes to the container for the compnoent.
  //
  // In this case, it will add `data-gap` and `data-gap-{breakpoint}` attributes
  // with the corresponding value set
  return <StyledStack {...getResponsiveAttributes('gap', gap)}>{children}</StyledStack>
}

const StyledStack = styled.div`
  &[data-gap='none'],
  &[data-gap-narrow='none'] {
    /* ... */
  }

  &[data-gap='condensed'],
  &[data-gap-narrow='condensed'] {
    /* ... */
  }

  /* ... */

  // @custom-media --viewportRange-regular
  @media (min-width: 768px) {
    &[data-gap-regular='none'] {
      /* ... */
    }

    &[data-gap-regular='condensed'] {
      /* ... */
    }

    /* ... */
  }

  // @custom-media --viewportRange-wide
  @media (min-width: 1400px) {
    &[data-gap-wide='none'] {
      /* ... */
    }

    &[data-gap-wide='condensed'] {
      /* ... */
    }

    /* ... */
  }
`
```

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

### Create a Changeset

Source: https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md

Use the 'npx changeset' command to create a changeset for managing package releases. This is typically done when preparing a pull request.

```bash
npx changeset
```

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

### Create components with styled-components

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-005-box-sx.md

Legacy pattern for creating components using styled-components.

```tsx
const Avatar = styled.img.attrs<StyledAvatarProps>(props => ({
  height: props.size,
  width: props.size,
}))<StyledAvatarProps>`
  display: inline-block;
  overflow: hidden;
  line-height: ${get('lineHeights.condensedUltra')};
  border-radius: ${props => getBorderRadius(props)};
  ${sx}
`
```

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

### Create components with Box

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-005-box-sx.md

Recommended pattern for creating components using the Box primitive to improve API consistency and type safety.

```tsx
const Avatar: React.FC<AvatarProps> = ({size = 20, alt = '', square = false, sx = {}, ...props}) => {
  const styles: BetterSystemStyleObject = {
    display: 'inline-block',
    overflow: 'hidden',
    lineHeight: 'condensedUltra',
    borderRadius: getBorderRadius({size, square}),
  }

  return (
    <Box
      as="img"
      alt={alt}
      sx={merge<BetterSystemStyleObject>(styles, sx)} // styles needs to merge with props.sx
      {...props}
    />
  )
}
```

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

### Flash component with icon as prop (recommended)

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

Passing the icon as a prop simplifies usage and ensures consistent styling by default. This makes the recommended path easier to follow.

```jsx
<Flash variant="success" icon={CheckIcon}>
  Changes saved!
</Flash>
```

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

### Define component and override styles

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-021-css-layers.md

Initial CSS implementation showing how component and override classes interact.

```css
/* v1.0.0 of a component */
.Component {
  color: var(--fgColor-default);
}

/* The override class placed on the same element as the component class */
.override {
  color: var(--fgColor-muted);
}
```

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

### Apply CSS Modules with sx prop support

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-016-css.md

Demonstrates how to combine CSS modules with the sx prop by passing both internal and external class names to a component.

```jsx
import clsx from 'clsx'
import classNames from './ActionList.module.css'

const Button = ({className, sx, ...props}}) => {
  return (
    <Box
      as="button"
      sx={sx}
      // it's important to pass both internal and props.className to the element
      className={clsx(classNames.ActionList, className)}
      {...props}
    >
    </Box>
  )
}
```

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

### VS Code MCP Server Configuration

Source: https://github.com/primer/react/blob/main/packages/mcp/README.md

This JSON configuration is used within VS Code to set up the Primer MCP server. It specifies the server type, command to execute, and arguments, enabling AI agents to connect to Primer's design system.

```json
{
  "servers": {
    "Primer": {
      "type": "stdio",
      "command": "npx",
      "args": ["@primer/mcp@latest"]
    }
  },
  "inputs": []
}
```

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

### Button component icon usage comparison

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

Illustrates the preferred method of using the 'leadingIcon' prop for icons in buttons over embedding them directly within children, emphasizing the benefits of controlled composition.

```jsx
// we prefer this:
<Button leadingIcon={SearchIcon}>Search</Button>
```

```jsx
// over these:
<Button><SearchIcon/> Search</Button>
<Button leadingIcon={<SearchIcon/>}>Search<Button>
```

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

### Enable keyboard navigation with useFocusZone

Source: https://context7.com/primer/react/llms.txt

Use the useFocusZone hook to manage arrow key navigation within a container. Supports both standard toolbar layouts and active descendant patterns for screen readers.

```tsx
import {useFocusZone, FocusKeys} from '@primer/react'

function ToolbarExample() {
  const {containerRef} = useFocusZone({
    bindKeys: FocusKeys.ArrowHorizontal | FocusKeys.HomeAndEnd,
    focusInStrategy: 'closest',
    focusOutBehavior: 'wrap', // wrap around at ends
  })

  return (
    <div
      ref={containerRef as React.RefObject<HTMLDivElement>}
      role="toolbar"
      aria-label="Formatting tools"
      style={{display: 'flex', gap: '4px'}}
    >
      <button>Bold</button>
      <button>Italic</button>
      <button>Underline</button>
      <button>Strikethrough</button>
    </div>
  )
}

// With active descendant pattern (for screen reader compatibility)
function ListboxExample() {
  const {containerRef, activeDescendantControlRef} = useFocusZone({
    bindKeys: FocusKeys.ArrowVertical,
    activeDescendantFocus: true,
  })

  return (
    <div
      ref={containerRef as React.RefObject<HTMLDivElement>}
      role="listbox"
      tabIndex={0}
    >
      <div role="option" id="option-1">Option 1</div>
      <div role="option" id="option-2">Option 2</div>
      <div role="option" id="option-3">Option 3</div>
    </div>
  )
}
```

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

### Create a responsive PageLayout

Source: https://context7.com/primer/react/llms.txt

Uses PageLayout to define a structured page with header, sidebar, content, and footer regions.

```tsx
import {PageLayout, NavList, Heading, Text} from '@primer/react'

function PageWithSidebar() {
  return (
    <PageLayout>
      <PageLayout.Header>
        <Heading as="h1">Repository Settings</Heading>
      </PageLayout.Header>

      <PageLayout.Pane position="start" width="small">
        <NavList>
          <NavList.Item href="#general" aria-current="page">General</NavList.Item>
          <NavList.Item href="#access">Access</NavList.Item>
          <NavList.Item href="#branches">Branches</NavList.Item>
          <NavList.Item href="#webhooks">Webhooks</NavList.Item>
        </NavList>
      </PageLayout.Pane>

      <PageLayout.Content>
        <Heading as="h2">General Settings</Heading>
        <Text as="p">Configure your repository's general settings here.</Text>
      </PageLayout.Content>

      <PageLayout.Footer>
        <Text>Footer content</Text>
      </PageLayout.Footer>
    </PageLayout>
  )
}
```

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

### Import Component Metadata

Source: https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md

Import component metadata from its docs.json file when creating a new component's documentation.

```javascript
import data from '../../../src/Component/Component.docs.json'
```

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

### Implement NavList sidebar navigation

Source: https://context7.com/primer/react/llms.txt

Demonstrates a sidebar navigation structure with nested sub-navigation, icons, and grouped items.

```tsx
import {NavList} from '@primer/react'
import {HomeIcon, RepoIcon, PersonIcon, GearIcon, BookIcon} from '@primer/octicons-react'

function SidebarNavigation() {
  return (
    <NavList aria-label="Main navigation">
      <NavList.Item href="/" aria-current="page">
        <NavList.LeadingVisual><HomeIcon /></NavList.LeadingVisual>
        Home
      </NavList.Item>

      <NavList.Item href="/repositories">
        <NavList.LeadingVisual><RepoIcon /></NavList.LeadingVisual>
        Repositories
        <NavList.TrailingVisual>12</NavList.TrailingVisual>
      </NavList.Item>

      {/* Nested sub-navigation */}
      <NavList.Item href="/docs" defaultOpen>
        <NavList.LeadingVisual><BookIcon /></NavList.LeadingVisual>
        Documentation
        <NavList.SubNav>
          <NavList.Item href="/docs/getting-started">Getting Started</NavList.Item>
          <NavList.Item href="/docs/components">Components</NavList.Item>
          <NavList.Item href="/docs/hooks">Hooks</NavList.Item>
        </NavList.SubNav>
      </NavList.Item>

      <NavList.Divider />

      <NavList.Group>
        <NavList.GroupHeading>Account</NavList.GroupHeading>
        <NavList.Item href="/profile">
          <NavList.LeadingVisual><PersonIcon /></NavList.LeadingVisual>
          Profile
        </NavList.Item>
        <NavList.Item href="/settings">
          <NavList.LeadingVisual><GearIcon /></NavList.LeadingVisual>
          Settings
        </NavList.Item>
      </NavList.Group>
    </NavList>
  )
}
```

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

### Using Pseudo-classes for State

Source: https://github.com/primer/react/blob/main/contributor-docs/authoring-css.md

Prefer pseudo-classes over modifier classes to handle component states.

```css
/* Do */
.Button:disabled {
  opacity: 0.5;
}

/* Don't */
.ButtonDisabled {
  opacity: 0.5;
}
```

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

### CSS Classname Compilation

Source: https://github.com/primer/react/blob/main/contributor-docs/authoring-css.md

Demonstrates how class names are prefixed and hashed during the build process.

```css
/* Before compilation */
.Container {
  display: inline-block;
}

/* After compilation */
.prc-Button-Container-cBBI {
  display: inline-block;
}
```

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

### Add Descriptions Below Code Samples

Source: https://github.com/primer/react/blob/main/contributor-docs/style.md

Add an extra row before `</tbody></table>` to include descriptions for side-by-side code samples.

```html
<tr>
<td>DESCRIBE UNPREFERRED CODE</td>
<td>DESCRIBE PREFERRED CODE</td>
</tr>
```

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

### Implement Tooltip for UI elements

Source: https://context7.com/primer/react/llms.txt

Shows how to attach tooltips to various trigger elements like buttons, icons, and links with different directional positioning.

```tsx
import {Tooltip, IconButton, Button, Link} from '@primer/react'
import {InfoIcon, QuestionIcon} from '@primer/octicons-react'

function TooltipExamples() {
  return (
    <div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>
      {/* Basic tooltip with IconButton */}
      <Tooltip text="More information" direction="s">
        <IconButton icon={InfoIcon} aria-label="Info" variant="invisible" />
      </Tooltip>

      {/* Tooltip on Button */}
      <Tooltip text="Save your changes (Ctrl+S)" direction="n">
        <Button>Save</Button>
      </Tooltip>

      {/* Different directions */}
      <Tooltip text="Tooltip on top" direction="n">
        <span>North</span>
      </Tooltip>
      <Tooltip text="Tooltip on right" direction="e">
        <span>East</span>
      </Tooltip>
      <Tooltip text="Tooltip below" direction="s">
        <span>South</span>
      </Tooltip>
      <Tooltip text="Tooltip on left" direction="w">
        <span>West</span>
      </Tooltip>

      {/* On links */}
      <Tooltip text="Opens in new tab">
        <Link href="https://github.com" target="_blank">GitHub</Link>
      </Tooltip>
    </div>
  )
}
```

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

### Button component with leading icon prop

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

Demonstrates the recommended pattern for including icons in buttons, where the icon is passed as a prop. This ensures the icon's color and margin are automatically managed based on the button's variant and size.

```jsx
<Button leadingIcon={SearchIcon}>Search</Button>
```

```jsx
<Button leadingIcon={SearchIcon} variant="primary" size="large">Search</Button>
```

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

### Update CSS Custom Property with Primer Primitives

Source: https://github.com/primer/react/blob/main/contributor-docs/versioning.md

Demonstrates safe versus breaking updates when migrating to new design tokens.

```diff
// This is not a breaking change if base-size-6 is defined in the current major
// version of Primer Primitives
.ExampleComponent {
-  margin-block: var(--space-small, 0.375rem);
+  margin-block: var(--base-size-6, 0.375rem);
}
```

```diff
// This is a breaking change if base-size-6 is defined in the next major
// version of Primer Primitives. A fallback should be used to ship this safely
.ExampleComponent {
-  margin-block: var(--space-small, 0.375rem);
+  margin-block: var(--base-size-6, var(--space-small, 0.375rem));
}
```

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

### Flash with CheckIcon and text

Source: https://github.com/primer/react/blob/main/contributor-docs/adrs/adr-004-children-as-api.md

Demonstrates composing a Flash component with an icon and text using the `children` prop.

```jsx
import {Flash} from '@primer/react'
import {CheckIcon} from '@primer/octicons-react'

render(
  <Flash variant="success">
    <CheckIcon /> Changes saved!
  </Flash>,
)
```

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

### Run Specific Unit Test

Source: https://github.com/primer/react/blob/main/contributor-docs/testing.md

Execute unit tests for a particular component. Useful for focused testing during development.

```bash
npm test ComponentName
```

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

### Implement a List component using data props

Source: https://github.com/primer/react/blob/main/contributor-docs/component-contents-api-patterns.md

Demonstrates a component where the component itself owns the rendering of the items provided via a data array.

```jsx
function List({items, ordered}) {
  const Elem = ordered ? 'ol' : 'ul'
  const listItems = items.map(i => <li key={i}>i</li>)
  return <Elem>{listItems}</Elem>
}

// usage
function MyApp() {
  return <List ordered={true} items={['Apple', 'Banana', 'Cantaloupe']} />
}
```

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

### Using :where for Low Specificity Selectors

Source: https://github.com/primer/react/blob/main/contributor-docs/authoring-css.md

Illustrates using the `:where` pseudo-class to create CSS selectors with zero specificity, useful for component options that rely on data attributes.

```css
/* Example using :where for data attributes */
&:where([data-size='small'])
```