npm package: @hotfix-patchui/react
Description: A React component library built on Base UI primitives with Tailwind CSS v4 and a custom design token system.
Latest version: 0.4.2

# @hotfix-patchui/react

A React component library built on [Base UI](https://base-ui.com/) primitives with Tailwind CSS v4 and a custom `--patch-*` design token system.

## Install

```bash
npm install @hotfix-patchui/react
```

### Peer Dependencies

The following must be installed in your project:

```bash
npm install react react-dom @base-ui/react
```

| Package | Version |
|---------|---------|
| `react` | `^19.0.0` |
| `react-dom` | `^19.0.0` |
| `@base-ui/react` | `^1.3.0` |

## Tailwind CSS v4 Setup

> **Important:** The token CSS must be imported through your Tailwind CSS file — not via a JavaScript import. The `@theme inline` block requires processing by Tailwind's CSS pipeline.

Add the following to your main CSS file (e.g. `app/globals.css`):

```css
@import "tailwindcss";
@import "@hotfix-patchui/react/theme/tokens.css";
@source "../node_modules/@hotfix-patchui/react/src";
```

- **`@import`** loads the design tokens and registers `--patch-*` colors as Tailwind utilities (e.g. `bg-patch-text`, `text-patch-error`)
- **`@source`** tells Tailwind to scan the library's source files so component classes aren't purged

### Light / Dark Mode

The tokens support light and dark mode out of the box. Add the `dark` class to your `<html>` or `<body>` element to switch:

```html
<html class="dark">
```

## Usage

```tsx
import { Button } from "@hotfix-patchui/react";

export default function App() {
  return (
    <div className="flex gap-3">
      <Button variant="primary">Save</Button>
      <Button variant="secondary">Cancel</Button>
      <Button variant="danger">Delete</Button>
    </div>
  );
}
```

## Components

| Component | Description |
|-----------|-------------|
| `Button` | Primary, secondary, danger, and link variants with loading state |
| `Input` | Text input with Base UI primitives |
| `Textarea` | Multi-line text input |
| `Label` | Form label |
| `Select` | Dropdown select with popup, items, groups |
| `Checkbox` | Checkbox with Base UI primitives |
| `Switch` | Toggle switch |
| `Slider` | Range slider with value display |
| `Card` | Card container with header, title, description, content, footer |
| `Badge` | Status badge with multiple variants |
| `Banner` | Alert/info banner |
| `Sheet` | Slide-out drawer panel (right, left, top, bottom) |
| `Dialog` | Modal dialog with header, footer, close |
| `Menu` | Dropdown menu with items, checkboxes, radio groups, submenus |
| `Tooltip` | Hover tooltip |
| `Separator` | Visual divider |
| `Collapsible` | Expandable/collapsible content |
| `Toast` | Toast notifications with position options |
| `Spinner` | Loading spinner |
| `Skeleton` | Loading placeholder |
| `ScrollArea` | Custom scrollbar area |
| `Field` / `Form` | Form field wrapper with label, description, error, validation |

## Design Tokens

The library uses CSS custom properties (`--patch-*`) for theming:

| Token | Light | Dark |
|-------|-------|------|
| `--patch-bg` | `#fafafa` | `#09090b` |
| `--patch-surface` | `#ffffff` | `#111113` |
| `--patch-text` | `#171717` | `#ededed` |
| `--patch-text-secondary` | `#525252` | `#a1a1a1` |
| `--patch-border` | `#e5e5e5` | `rgba(255,255,255,0.06)` |
| `--patch-error` | `#dc2626` | `#f87171` |
| `--patch-success` | `#16a34a` | `#4ade80` |
| `--patch-warning` | `#d97706` | `#fbbf24` |

Override any token in your own CSS to customize the theme.

## License

MIT