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

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

Step 2: Configure PostCSS

Create postcss.config.js in your project root:

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

Step 3: Setup your CSS file

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

@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

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

// 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.

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

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

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

Input

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

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

Typography

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

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

Avatar

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

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

Autocomplete

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 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 file for details.

🙏 Acknowledgments

• Built with React
• Styled with Tailwind CSS
• Documented with Storybook
• Bundled with tsup