npm package: @minidev.fun/ui
Description: AI-first React component library for coding agents. LLM-optimized docs, sensible defaults, zero config. Built on shadcn patterns, Base UI, and Tailwind CSS v4.
Author: Tokenfi Inc.
Latest version: 1.1.10

<h1 align="center">@minidev.fun/ui</h1>

<p align="center">
  <strong>Beautiful React components built on Base UI + Tailwind CSS v4</strong>
</p>

<p align="center">
  <a href="https://minidev.fun">🚀 Minidev</a>
</p>

---

## What is this? 🤔

@minidev.fun/ui is a full-featured React component library—the same components that power Minidev Studio and our suite of developer tools.

**One package. 50+ components. Tailwind CSS v4 powered.**

```css
/* src/index.css */
@import "@minidev.fun/ui/styles";
@import "@minidev.fun/ui/themes/minidev-sunset";
```

```tsx
import "./index.css";
import { Button } from "@minidev.fun/ui/button";
import { Card } from "@minidev.fun/ui/card";
import { Alert } from "@minidev.fun/ui/alert";

export default function App() {
  return (
    <Card>
      <Alert variant="success">Ready to ship 🚀</Alert>
      <Button>Get Started</Button>
    </Card>
  );
}
```

## Why @minidev.fun/ui? ✨

| Feature              | Description                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Built for AI**     | Designed for AI coding assistants—sensible defaults, clear APIs, zero config. LLMs love it.                |
| **Modern Stack**     | shadcn/ui patterns on Base UI primitives, Tailwind CSS v4, OKLCH colors, TypeScript-first.                 |
| **Production-Ready** | Battle-tested in Minidev Studio and used by developers building on Web3 & Farcaster.                       |
| **RSC-Ready**        | `"use client"` directives baked in. Use interactive components from Server Components—no wrapping needed.  |
| **Fully Accessible** | WCAG 2.1 AA compliant with keyboard navigation and screen reader support.                                  |
| **Themes**           | Ships with Minidev Sunset and First Light themes. Easy to customize or create your own with CSS variables. |

---

## Installation 📦

```bash
# npm
npm install @minidev.fun/ui

# pnpm
pnpm add @minidev.fun/ui

# yarn
yarn add @minidev.fun/ui
```

### Tailwind CSS v4 Setup (Required)

This package requires Tailwind CSS v4. The exported styles use `@import "tailwindcss"`.

**Vite:**

```bash
npm install tailwindcss @tailwindcss/vite
```

```ts
// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
export default defineConfig({ plugins: [react(), tailwindcss()] });
```

**Next.js:**

```bash
npm install tailwindcss @tailwindcss/postcss
```

```js
// postcss.config.js
export default { plugins: { "@tailwindcss/postcss": {} } };
```

---

## What's Included 🎁

### Full shadcn/ui Collection

This package includes the **complete set of shadcn/ui components**, rebuilt on [Base UI](https://base-ui.com) primitives with Tailwind CSS v4. Every component you'd expect, ready to use.

### Minidev Enhancements

Improvements we've made to existing components:

- **Toast (Sonner)** — Pre-configured with colored variants, custom icons, and `richColors` enabled by default
- **Extended Variants** — Semantic `success`, `warning`, and `info` variants added to Button, Badge, Alert, and Menu Items

### Components

| Category                   | Components                                                                                                      |
| -------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Core Inputs**            | Button, Checkbox, Combobox, Input, RadioGroup, Select, Slider, Switch, Textarea, Toggle, ToggleGroup            |
| **Form & Field**           | ButtonGroup, Calendar, Field, InputGroup, InputOTP, Label                                                       |
| **Layout & Structure**     | Accordion, AspectRatio, Card, Collapsible, Resizable, Separator, Table                                          |
| **Navigation & Menus**     | Breadcrumb, ContextMenu, DropdownMenu, Menubar, NavigationMenu, Pagination, Tabs                                |
| **Overlays & Dialogs**     | AlertDialog, Dialog, Drawer, HoverCard, Popover, Sheet, Tooltip                                                 |
| **Feedback & Status**      | Alert, Badge, Empty, Progress, Skeleton, Sonner, Spinner                                                        |
| **Advanced & Specialized** | Avatar, Carousel, Chart, Command, Kbd, ScrollArea, Sidebar                                                      |
| **Minidev Custom**         | ColorModeInitializer, ColorModeToggle, Title, Text, Code, Blockquote, Caption, Overline, Modal, ListItem, Toast |

### Hooks & Utilities

| Export                       | Description                                            |
| ---------------------------- | ------------------------------------------------------ |
| `@minidev.fun/ui/use-mobile` | `useMobile()` hook for responsive breakpoint detection |
| `@minidev.fun/ui/utils`      | `cn()` utility for merging Tailwind classes            |

---

## Import Examples 📝

Each component has its own export path:

```tsx
// Core components
import { Button } from "@minidev.fun/ui/button";
import { Input } from "@minidev.fun/ui/input";
import { Card, CardHeader, CardContent } from "@minidev.fun/ui/card";

// Color Mode
import {
  ColorModeInitializer,
  ColorModeToggle,
  useColorMode,
} from "@minidev.fun/ui/color-mode";

// Typography
import { Title, Text, Caption } from "@minidev.fun/ui/typography";

// Toast
import { Toaster, toast } from "@minidev.fun/ui/sonner";

// Utilities
import { cn } from "@minidev.fun/ui/utils";
import { useMobile } from "@minidev.fun/ui/use-mobile";
```

---

## Setup & Customization 🎨

Create a CSS file with your styles and theme:

```css
/* app/globals.css or src/index.css */
@import "@minidev.fun/ui/styles";
@import "@minidev.fun/ui/themes/minidev-sunset";
```

Then import the CSS file in your app entry:

```tsx
// main.tsx (Vite) or layout.tsx (Next.js)
import "./globals.css";
```

**Note:** Styles must be imported via CSS `@import`, not JS imports. The CSS files use `@import "tailwindcss"` which requires Tailwind processing.

See the [Theming Guide](./docs/theming/index.md) for the full list of customizable tokens.

### Color Mode

Zero-configuration dark mode:

```tsx
// Add to your root layout
<ColorModeInitializer />

// Drop in anywhere for user control
<ColorModeToggle />

// Programmatic access
const { mode, preference, setPreference } = useColorMode();
```

### Data Slots

All components include `data-slot` attributes for targeted CSS and testing:

```css
/* Style specific component parts */
[data-slot="dialog-content"] {
  backdrop-filter: blur(20px);
}
[data-slot="button"] {
  font-weight: 600;
}
```

```ts
// Stable E2E test selectors
page.locator('[data-slot="dialog-trigger"]').click();
```

---

## Framework Support 🛠️

Works with any React framework:

- **Next.js**
- **Vite**
- **Remix**
- **Astro**
- **TanStack Start**

---

## Documentation 📖

### Integration Guides

Framework-specific setup guides:

- [Next.js Integration](./docs/integrations/nextjs.md)
- [Vite Integration](./docs/integrations/vite.md) — React + Vite setup

### Reference

- [Component Reference](./docs/components.md) — Complete component catalog
- [Theming Guide](./docs/theming/index.md) — Themes, color mode, CSS variables
  - [ColorModeInitializer](./docs/theming/color-mode-initializer.md) — SSR-safe color mode setup
  - [useColorMode Hook](./docs/theming/use-color-mode.md) — Programmatic control
  - [Minidev Sunset Theme](./docs/theming/minidev-sunset.md) — Default theme reference
  - [First Light Theme](./docs/theming/first-light.md) — Hand-drawn aesthetic
- [Troubleshooting](./docs/troubleshooting.md) — Common issues and solutions

### For AI Assistants

LLM-optimized documentation for AI coding assistants:

- [LLM Documentation Guide](./docs/llm-documentation.md) — How to use our AI-optimized docs
- [llms.txt](./llms.txt) — Compact overview for quick context
- [llms-full.txt](./llms-full.txt) — Complete documentation (~16k lines)
- [llm/](./llm/) — Per-component markdown docs

---

## Credits

Made by the Minidev team.

Built on the shoulders of giants:

- [shadcn/ui](https://ui.shadcn.com) for the component patterns
- [Base UI](https://base-ui.com) for accessible primitives
- [Tailwind CSS](https://tailwindcss.com) for styling

---

<p align="center">
  MIT License · Made with 🧡 by <a href="https://minidev.fun">Minidev</a>
</p>