npm package: @metalbear/ui
Description: MetalBear Design System - React component library
Author: MetalBear
Latest version: 0.1.5

# @metalbear/ui

MetalBear Design System - A React component library built with Radix UI primitives and Tailwind CSS.

## Features

- 15+ accessible components built on [Radix UI](https://www.radix-ui.com/)
- Styled with [Tailwind CSS](https://tailwindcss.com/)
- Full TypeScript support
- Light and dark mode theming
- [Storybook](https://storybook.js.org/) documentation
- Tree-shakeable ESM and CJS builds

## Installation

```bash
pnpm add @metalbear/ui
```

### Peer Dependencies

Make sure you have React 18+ installed:

```bash
pnpm add react react-dom
```

## Usage

Import components and styles in your app:

```tsx
import { Button, Card, Input } from '@metalbear/ui'
import '@metalbear/ui/styles.css'

function App() {
  return (
    <Card>
      <Input placeholder="Enter your name" />
      <Button>Submit</Button>
    </Card>
  )
}
```

## Available Components

### Form Components
- `Button` - Primary action buttons with variants
- `Input` - Text input field
- `Textarea` - Multi-line text input
- `Checkbox` - Boolean selection
- `RadioGroup` - Single selection from options
- `Select` - Dropdown selection
- `Switch` - Toggle boolean state
- `Label` - Accessible form labels

### Layout Components
- `Card` - Content container with header/footer
- `Tabs` - Tabbed content navigation
- `Separator` - Visual divider

### Overlay Components
- `Dialog` - Modal dialog
- `Tooltip` - Hover information display

### Feedback Components
- `Badge` - Status indicator
- `Loader` - Loading spinner

## Development Setup

### Prerequisites

- Node.js 18+
- pnpm 8+

### Quick Start

```bash
# Clone the repository
git clone https://github.com/metalbear-co/ui.git
cd ui

# Install dependencies
pnpm install

# Start Storybook development server
pnpm dev
```

Storybook will be available at http://localhost:6006

### Available Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start Storybook dev server |
| `pnpm build` | Build the library for production |
| `pnpm build:storybook` | Build static Storybook site |
| `pnpm typecheck` | Run TypeScript type checking |
| `pnpm lint` | Run ESLint |
| `pnpm format` | Format code with Prettier |
| `pnpm format:check` | Check code formatting |

### Project Structure

```
ui/
├── .husky/              # Git hooks
├── .storybook/          # Storybook configuration
├── src/
│   ├── components/      # React components
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   └── index.ts
│   │   └── ...
│   ├── lib/
│   │   └── utils.ts     # Utility functions (cn helper)
│   ├── styles/
│   │   └── globals.css  # CSS variables and Tailwind
│   └── index.ts         # Main exports
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── vite.config.ts
```

### Adding a New Component

1. Create a new folder in `src/components/`
2. Add the component file (e.g., `MyComponent.tsx`)
3. Add stories (e.g., `MyComponent.stories.tsx`)
4. Add barrel export (`index.ts`)
5. Export from `src/components/index.ts`

## Theming

The design system uses CSS variables for theming. Override these in your app:

```css
:root {
  --primary: 244 85% 69%;        /* Main Purple */
  --secondary: 38 100% 74%;      /* Yellow */
  --background: 240 43% 99%;     /* Light Grey */
  --foreground: 0 0% 0%;         /* Black */
  --destructive: 359 85% 68%;    /* Blush Red */
}

.dark {
  --background: 243 33% 19%;     /* Dark Purple */
  --foreground: 240 43% 99%;     /* Light Grey */
}
```

## Brand Colors

| Color | Hex | Usage |
|-------|-----|-------|
| Main Purple | `#756DF3` | Primary actions, backgrounds |
| Yellow | `#FFCB7D` | Highlights, secondary actions |
| Medium Purple | `#E4E3FD` | Muted elements |
| Dark Purple | `#232141` | Dark mode background |
| Light Grey | `#FAFAFD` | Light mode background |
| Blush Red | `#F36869` | Destructive actions |

---

## Claude Code Setup Instructions

If you're using Claude Code, you can use the following prompt to set up this repository automatically:

```
Read the README at /path/to/ui/README.md and set up this design system repository for development. Run pnpm install and start Storybook.
```

### For Claude Code

To set up this repository:

1. **Install dependencies:**
   ```bash
   pnpm install
   ```

2. **Start development server:**
   ```bash
   pnpm dev
   ```

3. **Verify the setup:**
   - Storybook should be running at http://localhost:6006
   - You should see all components in the sidebar

4. **Before committing changes:**
   - The pre-commit hook will automatically format your code
   - Run `pnpm typecheck` to verify TypeScript types
   - Run `pnpm build` to verify the library builds

### Common Tasks for Claude

**Adding a new component:**
```
Create a new [ComponentName] component in the ui repo following the existing patterns. Include TypeScript types, Storybook stories with examples, and export it from the main index.
```

**Updating colors:**
```
Update the design system colors in tailwind.config.js and src/styles/globals.css to match the new brand palette.
```

**Building for production:**
```
Build the ui library and verify all components compile correctly.
```

---

## Publishing

The package is published to GitHub Packages. To publish a new version:

1. Update the version in `package.json`
2. Run `pnpm build`
3. Run `pnpm publish`