CLAUDE.md · heroui-inc/heroui

Sections

1. Repository Overview
2. Development Commands
3. Git Commit Convention
4. Repository Architecture
5. Development Workflow
6. Icon Library
7. Important Notes
8. Tailwind CSS Class Detection Rules
9. Figma Integration & MCP Server Rules
10. Library Documentation with Context7 MCP
11. GitHub Repository Search with Grep MCP
12. Agent-Specific Guidelines

First lines (shown under the repo's Apache-2.0 license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

HeroUI v3 is a modern React UI library built with Tailwind CSS v4, using a pnpm monorepo structure managed by Turborepo.

### Key Technical Stack

- **Node.js**: v22+ required
- **pnpm**: v10.26.2 (package manager)
- **React**: v19+
- **Tailwind CSS**: v4.3.3
- **TypeScript**: v5.9.3
- **Turborepo**: Build orchestration
- **Storybook**: Component development
- **Vitest**: Testing framework

Use the workspace manifests and lockfile as the source of truth for exact dependency versions.

## Development Commands

### Core Development Commands

```bash
# Install dependencies (use --hoist flag)
pnpm i --hoist

# Start Storybook for component development
pnpm dev

# Start documentation site
pnpm dev:docs

# Build libraries (styles + React)
pnpm build

# Build React and its dependencies
pnpm build:react

# Build docs or Storybook
pnpm build:docs
pnpm build:storybook

# Run linting
pnpm lint

# Run tests (turbo → packages with a test script; jsdom + browser)
pnpm test

# Filter by file name (e.g. button.test.tsx)
pnpm --filter @heroui/react exec vitest run button

# Coverage (jsdom floors only — not a depth bar)
pnpm test:coverage

# Changed-set (local jsdom only; not a merge gate)
pnpm --filter @heroui/react test:changed

# Check formatting
pnpm run format

# Apply formatting fixes
pnpm run format:fix

# Run type checking
pnpm typecheck
```

### Behavioral tests (`@heroui/react`)

- Suites: `packages/react/tests/components/<name>/` — `*.test.tsx` (jsdom), `*.ssr.test.tsx` (Client SSR via `ssrSmoke()`, not RSC), `*.browser.test.tsx` (Playwright for high-risk portals/overlays; not universal), optional `fixtures.tsx`
- Harness: `@heroui/testing/helpers` (`render`, `setupUser`, `runAllTimers`, `ssrSmoke`, `User`); browser `render` from `@heroui/testing/browser`. Sources via `@/`. Pattern testers: `user.createTester(...)` — do not import `createTester` directly
- Query/assert: role/label/text first; HeroUI `data-*` + light BEM + documented `data-slot` on compound parts; no colors, full class lists, or RAC internals
- Timers: fake timers per-suite only; wire `advanceTimers` into `setupUser` + `User`
- Naming: `describe("Component")`; nested concern; `it` as `supports…` / `calls…` / `exposes…` / `renders…`. SSR: `"Component SSR"`; browser: `"Component (browser)"`
- Intentional skips: internals (`rac`, `icons`), non-exported helpers (`color-input-group`, `date-input-group`), in-progress `calendar-year-picker`, parent-covered parts (`list-box-item`, `menu-item`, …), Toast SSR (client portal — jsdom + browser). Public `input-group` has its own suite. SSR/browser are risk-based
- Browser setup (once locally): `pnpm --filter @heroui/testing exec playwright install chromium` before `pnpm test`. PR QA uses the same command with `--with-deps`, then `pnpm test:browser` + `pnpm test:coverage`. Release CI installs Chromium and runs `pnpm test`
- Commands: `pnpm test` (jsdom + browser, needs Chromium); filter with `pnpm --filter @heroui/react exec vitest run <name>`
- Coverage: jsdom-only floors — green ≠ depth. Browser suites contribute nothing to the coverage number. Floors are a ratchet kept ~1pt under the measured run: raise them as coverage improves, never lower them to go green. `test:changed`: local jsdom shortcut only, not a merge gate
- SSR/browser suites are risk-based — see "When a component needs an SSR or browser suite" in `AGENTS.md`. Add a browser suite when correctness depends on real layout, pointer capture, portal focus containment, or transitions; do not fake geometry in jsdom to chase coverage

### Package-Specific Commands

- For a specific package and its build dependencies, run `pnpm exec turbo build --filter=<package-name>` from the root. The root `pnpm build` script already filters to styles and React; use `build:docs` / `build:storybook` for those apps.
- Main packages: `@heroui/react`, `@heroui/styles`, `@heroui/docs`, `@heroui/storybook`

## Git Commit Convention

**IMPORTANT**: This repository uses conventional commits with strict validation. All commits must follow this format:

```
<type>(<scope>): <message>
```

### Allowed Types:

- `feat` / `feature`: New features
- `fix`: Bug fixes
- `refactor`: Code refactoring
- `style`: Code style changes
- `revert`: Revert previous changes
- `docs`: Documentation changes
- `build`: Build system changes
- `test`: Test changes
- `ci`: CI configuration changes
- `chore`: Other changes

### Examples:

```bash
git commit -m "feat(components): add new prop to avatar component"
git commit -m "fix(button): resolve click handler issue"
git commit -m "docs: update installation guide"
git commit -m "ci: add Claude Code GitHub Action workflow"
```

**Note**: Commits without proper format will be rejected by git hooks.

## Repository Architecture

### Monorepo Structure

```
/
├── apps/
│   └── docs/          # Documentation site (Next.js + Fumadocs)
├── packages/
│   ├── react/         # Main UI component library (@heroui/react)
│   ├── styles/        # CSS styles & variants (@heroui/styles)
│   │   ├── components/     # Per-component .css files (flat, e.g. button.css)
│   │   ├── themes/         # Theme variables
│   │   └── src/components/ # Per-component .styles.ts (tailwind-variants)
│   ├── standard/      # Shared ESLint, Prettier, TypeScript configs
│   ├── storybook/     # Storybook configuration
│   └── testing/       # Shared test harness (@heroui/testing)
├── turbo.json         # Turborepo configuration
└── pnpm-workspace.yaml # Workspace definition
```

### Component Architecture Pattern

Each component in `packages/react/src/components/` follows this structure:

```
component-name/
├── component-name.tsx      # Main component (uses React Aria)
├── component-name.stories.tsx # Storybook stories (title: "Components/ComponentName")
└── index.ts               # Barrel exports
```

Styling lives in `@heroui/styles`, not next to the component:

```
packages/styles/src/components/component-name/component-name.styles.ts  # tv() props → BEM class names
packages/styles/components/component-name.css                           # BEM class definitions
```

**IMPORTANT**: All Storybook stories must use the "Components" group in their title. For example: `title: "Components/Card"`, `title: "Components/Button"`, etc.