shadcn/ui — AGENTS.md

# shadcn/ui — AGENTS.md

## Overview

shadcn/ui is a collection of reusable components built with Radix UI and Tailwind CSS. Components are designed to be copied into your project, not installed as a dependency.

## Repository Structure

```
apps/
  www/          # Documentation site (Next.js)
  v0/           # v0 integration
packages/
  cli/          # shadcn CLI
  shadcn/       # Core package
```

## Development

```bash
pnpm install
pnpm dev          # Start docs site
pnpm build        # Build all packages
pnpm test         # Run tests
```

## Component Principles

- Components use Radix UI primitives for accessibility.
- Tailwind CSS for styling — `cn()` utility for class merging.
- Each component should be fully self-contained when copied.
- `data-slot` attributes for targeting child elements.
- Support `className` prop for easy customization.

## Adding a New Component

1. Create in `packages/shadcn/src/components/`.
2. Export from `index.ts`.
3. Write tests in `__tests__/`.
4. Add docs page in `apps/www/content/docs/components/`.
5. Update CLI registry.

## Accessibility

- All interactive components must be keyboard navigable.
- Include proper ARIA attributes.
- Follow WAI-ARIA patterns.
- Test with screen readers.

## Theming

- CSS variables for colors: `--background`, `--foreground`, etc.
- Support both light and dark modes.
- Don't hardcode colors — always use CSS variables.

## Code Style

- TypeScript strict mode.
- Prettier + ESLint enforced.
- `forwardRef` for all components that wrap DOM elements.
- Consistent prop naming: `className`, `asChild`, `disabled`.