@shopify/shop-minis-react/README.md

React component library for Shopify Shop Minis with Tailwind CSS v4 support (source-only, requires TypeScript)

# @shopify/shop-minis-react

React component library for Shopify Shop Minis with Tailwind CSS v4 support. This library provides a comprehensive set of components with minimal setup required for consumers.

## Features

- 🎨 **Tailwind CSS v4** with CSS-first design tokens
- 📦 **Source-only distribution** for optimal tree-shaking
- 🎯 **TypeScript** first with full type safety
- 🔧 **Minimal setup** for consumers
- 🎭 **Dark mode** support out of the box
- ♿ **Accessible** components built with Radix UI

## Installation

```bash
pnpm add @shopify/shop-minis-react
# or
npm install @shopify/shop-minis-react
# or
yarn add @shopify/shop-minis-react
```

### Peer Dependencies

```bash
pnpm add react react-dom tailwindcss typescript
```

## Quick Setup

### 1. Import Styles

Add the library's CSS to your main CSS file or app entry point:

```css
/* src/index.css or src/app.css */
@import "@shopify/shop-minis-react/styles";

/* Your custom styles */
@layer base {
  :root {
    /* Override CSS variables if needed */
    --radius: 0.5rem;
  }
}
```

### 2. Use Components

```tsx
import { Button, Card, CardContent, CardHeader, CardTitle } from '@shopify/shop-minis-react'

function App() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello Shop Minis</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Click me</Button>
      </CardContent>
    </Card>
  )
}
```

## Advanced Configuration

### Custom Theme

You can customize the design system by overriding theme variables:

```css
:root {
  /* Customize primary brand color */
  --theme-primary: #00843d;
  --theme-primary-foreground: #ffffff;

  /* Customize other semantic colors */
  --theme-secondary: #f0f0f0;
  --theme-destructive: #cc0000;

  /* Customize border radius */
  --radius: 0.75rem;
}

.dark {
  --theme-primary: #10b554;
  --theme-background: #1a1a1a;
}
```

See [THEME-CUSTOMIZATION.md](./THEME-CUSTOMIZATION.md) for detailed customization options.

### Vite Configuration

For optimal development experience with Vite:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  optimizeDeps: {
    include: ['@shopify/shop-minis-react']
  }
})
```

## Component Philosophy

This library follows a **source-only** distribution model, meaning:

- ✅ **Tree-shaking friendly** - Only import what you use
- ✅ **TypeScript native** - Full type safety without compilation artifacts
- ✅ **CSS-first theming** - Customize appearance via CSS variables
- ✅ **Build-time optimization** - Components are optimized with your build

## Available Components

- **Layout**: Card, Container, Grid
- **Forms**: Button, Input, Label, Textarea
- **Feedback**: Alert, Toast, Loading
- **Navigation**: Tabs, Breadcrumb
- **Overlays**: Dialog, Popover, Tooltip
- **Data Display**: Badge, Avatar, Separator

## Troubleshooting

### Styles Missing or Components Look Unstyled

If your components appear unstyled, it's likely a Tailwind content scanning issue:

1. **Ensure CSS is imported:**
   ```css
   @import "@shopify/shop-minis-react/styles";
   ```

2. **Check Tailwind content scanning:**
   Your `tailwind.config.js` must include our library files:
   ```js
   content: [
     './src/**/*.{js,ts,jsx,tsx}',
     // This line is CRITICAL:
     './node_modules/@shopify/shop-minis-react/src/**/*.{js,ts,jsx,tsx}',
   ]
   ```

3. **Use our preset (easiest):**
   ```js
   const shopMinisConfig = require('@shopify/shop-minis-react/tailwind')
   module.exports = { ...shopMinisConfig, /* your config */ }
   ```

4. **Verify build process:**
   Ensure your build tool processes the imported CSS file.

## Contributing

This package is part of the Shopify Shop Client monorepo. Please refer to the main repository for contribution guidelines.

## License

See LICENSE.txt for details.