npm package: @neoptocom/neopto-ui
Description: A modern React component library built with Tailwind CSS v4 and TypeScript. Features dark mode, design tokens, and comprehensive documentation. Requires Tailwind v4+.
Author: Victor Brito
Latest version: 1.6.12

# NeoPTO UI

A modern React component library built with Tailwind CSS v4 and TypeScript. Features dark mode, design tokens, and comprehensive documentation.

> ⚠️ **Requirements:** This library requires **Tailwind CSS v4** and **@tailwindcss/postcss** in your project. See installation steps below.

## 🚀 Features

- **Modern Stack**: Built with React 18+, TypeScript, and Tailwind CSS v4+
- **Design System**: Comprehensive design token system with dark mode support
- **Type Safe**: Full TypeScript support with exported types
- **Accessible**: Built with accessibility in mind
- **Tree Shakable**: Optimized bundle size with tree shaking
- **Documentation**: Comprehensive documentation site with interactive examples

## 📦 Installation

### Step 1: Install the library and Tailwind CSS v4

```bash
npm install @neoptocom/neopto-ui
npm install -D tailwindcss@latest @tailwindcss/postcss
```

### Step 2: Configure PostCSS

Create `postcss.config.js` in your project root:

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

### Step 3: Setup your CSS file

If your CSS file is at `src/app/globals.css` (App Router), use:

```css
@import "tailwindcss";

/* Enable dark mode support */
@variant dark (&:where(.dark, .dark *));

/* Scan the component library source files */
@source "../../node_modules/@neoptocom/neopto-ui/src";

/* Import library styles */
@import "@neoptocom/neopto-ui/styles";

/* Scan your own project files */
@source "../";
```

**Note:** The path is relative to your CSS file location. Adjust `../` levels accordingly.

**Important:** The `@variant dark` line is required for dark mode to work properly with components like `AppBackground`.

```

Then import this CSS in your `src/main.tsx`:

```tsx
import "./index.css";
```

## 🎨 Usage

### Basic Example

```tsx
import { Button, Input, Typo } from "@neoptocom/neopto-ui";

function App() {
  return (
    <div className="p-8">
      <Typo variant="headline-lg">Welcome to My UI Library</Typo>
      <Input placeholder="Enter your name" />
      <Button variant="primary">Get Started</Button>
    </div>
  );
}
```

### Dark Mode

```tsx
// Enable dark mode
document.documentElement.classList.add("dark");

// Toggle dark mode
document.documentElement.classList.toggle("dark");
```

## Why Tailwind CSS v4 is Required

This library uses **Tailwind CSS v4** utility classes directly in components (e.g., `gap-2`, `px-4`, `hover:bg-cyan-400`). Your build tool needs Tailwind to process these classes into actual CSS.

**Note:** This library requires Tailwind v4+. If you're using Tailwind v3, please upgrade to v4.

## 🧩 Components

### AppBackground

A full-page background component with built-in light/dark mode support and smooth transitions.

```tsx
import { AppBackground } from "@neoptocom/neopto-ui";

// Use default NeoPTO branded backgrounds (recommended)
<AppBackground>
  <YourApp />
</AppBackground>

// Or use custom images
<AppBackground
  lightImage="/path/to/light-bg.jpg"
  darkImage="/path/to/dark-bg.jpg"
>
  <YourApp />
</AppBackground>
```

**Best Practice:** Add `AppBackground` to your root layout (`app/layout.tsx`) so it wraps your entire app and persists across pages.

### Button

```tsx
import { Button } from "@neoptocom/neopto-ui";

<Button variant="primary" size="md">
  Click me
</Button>;
```

### Input

```tsx
import { Input } from "@neoptocom/neopto-ui";

<Input placeholder="Enter text" size="md" />;
```

### Typography

```tsx
import { Typo } from "@neoptocom/neopto-ui";

<Typo variant="headline-lg" bold="semibold">
  Heading Text
</Typo>;
```

### Avatar

```tsx
import { Avatar, AvatarGroup } from "@neoptocom/neopto-ui";

<AvatarGroup max={3}>
  <Avatar name="John Doe" src="/avatar.jpg" />
  <Avatar name="Jane Smith" />
</AvatarGroup>;
```

### Autocomplete

```tsx
import { Autocomplete } from "@neoptocom/neopto-ui";

const options = [
  { label: "Option 1", value: "1" },
  { label: "Option 2", value: "2" },
];

<Autocomplete
  title="Select Option"
  options={options}
  selectedOption={selected}
  onSelect={setSelected}
/>;
```

## 🎨 Design Tokens

The library uses a comprehensive design token system:

- **Colors**: Brand, semantic colors with dark mode support
- **Typography**: Poppins for headings, Roboto for body text
- **Spacing**: Consistent spacing scale
- **Border Radius**: Configurable border radius values
- **Shadows**: Subtle shadow system
- **Motion**: Consistent animation timing

## 📚 Documentation

Visit our [documentation site](https://neoptocom.github.io/neopto-ui/docs) for:

- Interactive component playground
- Design system guidelines
- Usage examples
- Accessibility information
- Getting started guide
- Design tokens reference

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [React](https://reactjs.org/)
- Styled with [Tailwind CSS](https://tailwindcss.com/)
- Documented with [Storybook](https://storybook.js.org/)
- Bundled with [tsup](https://tsup.egoist.sh/)