niva-ui/README.md

A beautiful, minimalistic React + Tailwind UI framework for SaaS applications

# Niva UI

<div align="center">
  <h1>🌊 Niva UI</h1>
  <p><strong>Shape Your Interface. Your Way.</strong></p>
  <p>A beautiful, minimalistic React + Tailwind UI framework for SaaS applications</p>
</div>

<div align="center">

[![NPM Version](https://img.shields.io/npm/v/niva-ui)](https://www.npmjs.com/package/niva-ui)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-CSS-38bdf8)](https://tailwindcss.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

</div>

## ✨ Features

- 🎨 **Beautiful & Minimalistic** - Clean, modern design perfect for SaaS applications
- ⚡ **Tailwind Native** - Built with Tailwind CSS for maximum customization
- 🔧 **Fully Customizable** - Theme everything via configuration
- 📱 **Responsive by Default** - Mobile-first responsive design
- ♿ **Accessible** - WAI-ARIA compliant with keyboard navigation
- 🌙 **Dark Mode Ready** - Built-in dark mode support
- 📦 **Tree Shakeable** - Import only what you need
- 🔤 **TypeScript First** - Full type safety out of the box

## 🚀 Quick Start

### Installation

```bash
npm install niva-ui
```

### Setup

1. **Install Tailwind CSS** (if you haven't already):

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

2. **Configure Tailwind** to include Niva UI:

```js
// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/niva-ui/**/*.{js,ts,jsx,tsx}", // Add this line
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}
```

3. **Import Niva UI styles** in your CSS:

```css
/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
```

### Basic Usage

```tsx
import { Button, Card } from 'niva-ui'

function App() {
  return (
    <Card className="p-6">
      <h1 className="text-2xl font-bold mb-4">Welcome to Niva UI</h1>
      <Button variant="primary" size="lg">
        Get Started
      </Button>
    </Card>
  )
}
```

## 📚 Components

### Core Components

- **Button** - Primary actions with multiple variants
- **Card** - Content containers with slots
- **Badge** - Status indicators and labels
- **Avatar** - User profile images and initials
- **Input** - Form inputs with validation states

### Layout Components

- **Container** - Responsive page containers
- **Stack** - Vertical and horizontal layouts
- **Grid** - Responsive grid system
- **Flex** - Flexible layouts

### SaaS-Specific Components

- **Dashboard Layout** - Pre-built dashboard structure
- **Metric Cards** - KPI and statistics display
- **User Profile** - User information components
- **Pricing Cards** - Subscription plan displays
- **Settings Panels** - Configuration interfaces

## 🎨 Customization

### Theme Configuration

Create a `niva.config.js` file to customize your theme:

```js
export default {
  theme: {
    colors: {
      primary: '#6366f1',
      secondary: '#14b8a6',
      accent: '#f59e0b',
    },
    borderRadius: {
      sm: '0.375rem',
      md: '0.5rem',
      lg: '0.75rem',
    },
    spacing: {
      xs: '0.5rem',
      sm: '1rem',
      md: '1.5rem',
      lg: '2rem',
    }
  },
  components: {
    Button: {
      defaultVariant: 'primary',
      defaultSize: 'md',
    },
    Card: {
      defaultVariant: 'elevated',
    }
  }
}
```

### Component Variants

Each component supports multiple variants and sizes:

```tsx
// Button variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Button sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
<Button size="xl">Extra Large</Button>
```

## 🛠 CLI Tools

Niva UI comes with powerful CLI tools to speed up development:

```bash
# Install CLI globally
npm install -g @niva-ui/cli

# Create new components
npx niva create button
npx niva create card --variant elevated

# Generate theme
npx niva theme modern-dark

# Launch playground
npx niva playground

# Export to Figma
npx niva export-figma
```

## 📖 Documentation

- **[Getting Started](https://niva-ui.dev/docs/getting-started)** - Setup and basic usage
- **[Components](https://niva-ui.dev/docs/components)** - Complete component reference
- **[Theming](https://niva-ui.dev/docs/theming)** - Customization guide
- **[Examples](https://niva-ui.dev/examples)** - Real-world examples
- **[CLI Reference](https://niva-ui.dev/docs/cli)** - Command-line tools

## 🎮 Playground

Try Niva UI components in our interactive playground:

- **[Online Playground](https://niva-ui.dev/playground)** - Browser-based editor
- **[CodeSandbox Template](https://codesandbox.io/s/niva-ui-template)** - Ready-to-use template
- **[Figma Kit](https://figma.com/niva-ui)** - Design system for Figma

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

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

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build library
npm run build
```

## 📄 License

MIT © [Niva UI Team](https://github.com/sh20raj/niva-ui)

## 🙏 Acknowledgments

- Inspired by [Shadcn/ui](https://ui.shadcn.com/)
- Built with [Tailwind CSS](https://tailwindcss.com/)
- Powered by [Radix UI](https://www.radix-ui.com/)

---

<div align="center">
  <p>Made with ❤️ for the SaaS community</p>
  <p>
    <a href="https://niva-ui.dev">Website</a> •
    <a href="https://niva-ui.dev/docs">Documentation</a> •
    <a href="https://niva-ui.dev/examples">Examples</a> •
    <a href="https://github.com/sh20raj/niva-ui">GitHub</a>
  </p>
</div>