# Ninna UI

> Full React UI library with zero runtime theming and native Tailwind CSS v4 support.
> Website: https://ninna-ui.dev
> GitHub: https://github.com/ninna-ui/ninna-ui
> npm: https://www.npmjs.com/org/ninna-ui

Ninna UI is a production-ready React component library that combines Chakra-level component quality with DaisyUI-simple CSS theming. 69 accessible components across 12 tree-shakeable packages. Zero JavaScript theming runtime - pure CSS custom properties with oklch perceptual colors and guaranteed WCAG AA contrast.

## Why Ninna UI (Key Differentiators)

1. **CSS-First Theming** - One CSS import for a complete design system. No ThemeProvider, no context wrappers, no JavaScript configuration. Zero hydration cost.
2. **Radix Accessibility, Zero API Leakage** - 11 Radix primitives wrapped behind clean TypeScript engine interfaces. Your code never imports Radix.
3. **Tailwind CSS v4.1 Native** - CSS-first configuration. No tailwind.config.ts. Automated @source inline() safelisting for npm consumers.
4. **oklch Perceptual Colors** - All 8 semantic colors use oklch color space for perceptually uniform results and guaranteed WCAG AA contrast.
5. **98 data-slot CSS Targets** - Target any component internal element with plain CSS selectors. No !important hacks, no component forks.
6. **12 Tree-Shakeable Packages** - ESM-only, sideEffects-free. Install only what you need. No monolithic runtime.

## Packages (12)

- @ninna-ui/core - Design system engine: TypeScript tokens, Tailwind class mappings, 5 CSS theme presets with oklch colors
- @ninna-ui/primitives - 14 components: Avatar, Badge, Blockquote, Button, Code, Divider, Heading, IconButton, Kbd, Link, LinkOverlay, List, Mark, Text
- @ninna-ui/feedback - 8 components: Alert, CircularProgress, EmptyState, Loading, Progress, Skeleton, Status, Toast
- @ninna-ui/forms - 17 components: Checkbox, CheckboxGroup, Field, FileUpload, FormControl, FormGroup, FormLabel, FormMessage, HiddenField, Input, InputGroup, NumberInput, PinInput, RadioGroup, Select, Slider, Switch, Textarea
- @ninna-ui/layout - 10 components: AspectRatio, Box, Center, Container, Flex, Grid, Separator, SimpleGrid, Stack, Wrap
- @ninna-ui/overlays - 5 components: Drawer, DropdownMenu, Modal, Popover, Tooltip
- @ninna-ui/navigation - 5 components: Accordion, Breadcrumbs, Pagination, Stepper, Tabs
- @ninna-ui/data-display - 7 components: Calendar, Card, DataTable, Stat, Table, Timeline, Tree
- @ninna-ui/code-block - 1 component: CodeBlock with regex tokenizer (no Prism/Shiki dependency)
- @ninna-ui/utils - Internal: cn(), composeRefs, createContext, keyboard constants, SSR helpers
- @ninna-ui/react-internal - Internal: Radix UI engine adapters isolating Radix behind clean interfaces
- @ninna-ui/cli - Project scaffolding CLI with 3 framework templates

## Quick Start

```bash
npx @ninna-ui/cli init my-app
```

## Manual Installation

```bash
pnpm add @ninna-ui/primitives @ninna-ui/feedback @ninna-ui/forms @ninna-ui/layout @ninna-ui/overlays @ninna-ui/navigation @ninna-ui/data-display
```

## CSS Setup (Required)

```css
@import "tailwindcss";
@import "@ninna-ui/core/theme/presets/default.css";
@variant dark (&:is(.dark *));
```

## Usage Example

```tsx
import { Button } from "@ninna-ui/primitives";
import { Alert } from "@ninna-ui/feedback";
import { Input, Field } from "@ninna-ui/forms";
import { VStack } from "@ninna-ui/layout";

export default function App() {
  return (
    <VStack gap={4}>
      <Field label="Email">
        <Input placeholder="you@example.com" />
      </Field>
      <Button color="primary">Submit</Button>
      <Alert color="success" variant="soft">All components support 8 semantic colors and 5 variants.</Alert>
    </VStack>
  );
}
```

## Theme Presets (5)

- default - Purple/Magenta, vibrant and electric
- ocean - Blue/Cyan, cool and professional
- sunset - Orange/Rose, warm and bold
- forest - Green/Amber, natural and earthy
- minimal - Monochrome, clean and understated

## Architecture Highlights (for AI agents)

- Component structure: 4-file canonical pattern (ComponentName.tsx, ComponentName.styles.ts, index.ts, __tests__/)
- Every component: forwardRef, displayName, data-slot attributes, cn() class merging, className prop
- Styling: Pure CSS custom properties, no dark: utility classes, no hardcoded colors
- Accessibility: WCAG 2.1 AA, automated vitest-axe audits, 700+ tests
- Build: ESM-only, TypeScript strict, no 'use client' directives in library code
- Theming: Zero-config via CSS imports, dark mode via prefers-color-scheme or .dark class

## Framework Support

- Vite 7 + React 19 (SPA) - @tailwindcss/vite plugin
- Next.js 15 App Router (SSR) - @tailwindcss/postcss plugin
- React Router v7 (SSR/SPA) - @tailwindcss/vite plugin

## UI Blocks (40 free, copy-paste ready)

All blocks are free during our launch period and built entirely with Ninna UI + Tailwind CSS v4. Copy the source code and paste into any React project.

### How to use blocks
1. Browse: https://ninna-ui.dev/blocks
2. Pick a block and click "Copy" to grab the full source code
3. Paste into your React project and customize with Tailwind CSS

### Authentication (4 blocks)
- Block: Sign In - https://ninna-ui.dev/blocks/authentication-login
- Block: Sign Up - https://ninna-ui.dev/blocks/authentication-signup
- Block: Reset Password - https://ninna-ui.dev/blocks/authentication-reset-password
- Block: OTP Verification - https://ninna-ui.dev/blocks/authentication-otp-verify
- Category page: https://ninna-ui.dev/blocks/authentication

### Ecommerce (4 blocks)
- Block: Product Card Grid - https://ninna-ui.dev/blocks/product-card-grid
- Block: Shopping Cart - https://ninna-ui.dev/blocks/shopping-cart
- Block: Checkout Form - https://ninna-ui.dev/blocks/checkout-form
- Block: Order Confirmation - https://ninna-ui.dev/blocks/order-confirmation
- Category page: https://ninna-ui.dev/blocks/ecommerce

### Application UI (6 blocks)
- Block: Settings Page - https://ninna-ui.dev/blocks/settings-page
- Block: User Profile - https://ninna-ui.dev/blocks/user-profile
- Block: Notifications Panel - https://ninna-ui.dev/blocks/notifications-panel
- Block: Onboarding Wizard - https://ninna-ui.dev/blocks/onboarding-wizard
- Block: Command Palette - https://ninna-ui.dev/blocks/command-palette
- Block: File Upload Zone - https://ninna-ui.dev/blocks/file-upload-zone
- Category page: https://ninna-ui.dev/blocks/application-ui

### Data Display (4 blocks)
- Block: Dashboard - https://ninna-ui.dev/blocks/dashboard
- Block: Data Table with Filters - https://ninna-ui.dev/blocks/data-table-filters
- Block: Calendar with Events - https://ninna-ui.dev/blocks/calendar-events
- Block: Activity Timeline - https://ninna-ui.dev/blocks/timeline-activity
- Category page: https://ninna-ui.dev/blocks/data-display

### Page Sections (9 blocks)
- Block: Hero Header - https://ninna-ui.dev/blocks/hero-header
- Block: Testimonials Carousel - https://ninna-ui.dev/blocks/testimonials-carousel
- Block: Stats & Metrics - https://ninna-ui.dev/blocks/stats-counter
- Block: Team Grid - https://ninna-ui.dev/blocks/team-grid
- Block: Call to Action Banner - https://ninna-ui.dev/blocks/cta-banner
- Block: Features Grid - https://ninna-ui.dev/blocks/features-grid
- Block: Pricing Table - https://ninna-ui.dev/blocks/pricing-table
- Block: FAQ Section - https://ninna-ui.dev/blocks/faq-accordion
- Block: Contact Form - https://ninna-ui.dev/blocks/contact-form
- Category page: https://ninna-ui.dev/blocks/page-sections

### Marketing (3 blocks)
- Block: Split Marketing Hero - https://ninna-ui.dev/blocks/landing-hero-split
- Block: Feature Comparison - https://ninna-ui.dev/blocks/feature-comparison-table
- Block: Social Proof Banner - https://ninna-ui.dev/blocks/social-proof-banner
- Category page: https://ninna-ui.dev/blocks/marketing

### Error Pages (4 blocks)
- Block: Error 404 - https://ninna-ui.dev/blocks/error-404
- Block: Error 500 - https://ninna-ui.dev/blocks/error-500
- Block: Error 403 - https://ninna-ui.dev/blocks/error-403
- Block: Maintenance Page - https://ninna-ui.dev/blocks/maintenance
- Category page: https://ninna-ui.dev/blocks/error-pages

### Blog UI (6 blocks)
- Block: Article Card Grid - https://ninna-ui.dev/blocks/article-cards
- Block: Article Page - https://ninna-ui.dev/blocks/article-page
- Block: Newsletter Subscribe - https://ninna-ui.dev/blocks/newsletter-section
- Block: Blog Category Filter - https://ninna-ui.dev/blocks/blog-category-filter
- Block: Comments Section - https://ninna-ui.dev/blocks/comments-section
- Block: Changelog - https://ninna-ui.dev/blocks/changelog
- Category page: https://ninna-ui.dev/blocks/blog-ui

## Templates (coming soon)

Full-page starter kits for SaaS dashboards, e-commerce stores, portfolios, and blogs.
- Templates page: https://ninna-ui.dev/templates

## Documentation

- Landing page: https://ninna-ui.dev/
- Introduction: https://ninna-ui.dev/docs
- Blocks hub: https://ninna-ui.dev/blocks
- Getting started: https://ninna-ui.dev/getting-started/installation
- Theming guide: https://ninna-ui.dev/getting-started/theming
- Styling guide: https://ninna-ui.dev/getting-started/styling
- Color system: https://ninna-ui.dev/getting-started/colors
- Next.js guide: https://ninna-ui.dev/getting-started/nextjs
- Vite guide: https://ninna-ui.dev/getting-started/vite
- React Router guide: https://ninna-ui.dev/getting-started/react-router
- Library comparison: https://ninna-ui.dev/comparison
- Compare libraries hub: https://ninna-ui.dev/compare
- shadcn/ui vs Ninna UI: https://ninna-ui.dev/compare/shadcn-vs-ninna-ui
- Chakra UI vs Ninna UI: https://ninna-ui.dev/compare/chakra-vs-ninna-ui
- Mantine vs Ninna UI: https://ninna-ui.dev/compare/mantine-vs-ninna-ui
- DaisyUI vs Ninna UI: https://ninna-ui.dev/compare/daisyui-vs-ninna-ui
- Radix UI vs Ninna UI: https://ninna-ui.dev/compare/radix-vs-ninna-ui
- Material UI vs Ninna UI: https://ninna-ui.dev/compare/mui-vs-ninna-ui
- HeroUI vs Ninna UI: https://ninna-ui.dev/compare/heroui-vs-ninna-ui
- Ark UI vs Ninna UI: https://ninna-ui.dev/compare/ark-ui-vs-ninna-ui
- Bootstrap vs Ninna UI: https://ninna-ui.dev/compare/bootstrap-vs-ninna-ui
- Bulma vs Ninna UI: https://ninna-ui.dev/compare/bulma-vs-ninna-ui
- Ant Design vs Ninna UI: https://ninna-ui.dev/compare/ant-design-vs-ninna-ui
- Flowbite vs Ninna UI: https://ninna-ui.dev/compare/flowbite-vs-ninna-ui
- Preline UI vs Ninna UI: https://ninna-ui.dev/compare/preline-vs-ninna-ui
- shadcn/ui alternative: https://ninna-ui.dev/alternative/shadcn
- Chakra UI alternative: https://ninna-ui.dev/alternative/chakra
- Mantine alternative: https://ninna-ui.dev/alternative/mantine
- DaisyUI alternative: https://ninna-ui.dev/alternative/daisyui
- Radix UI alternative: https://ninna-ui.dev/alternative/radix
- Material UI alternative: https://ninna-ui.dev/alternative/mui
- HeroUI alternative: https://ninna-ui.dev/alternative/heroui
- Ark UI alternative: https://ninna-ui.dev/alternative/ark-ui
- Bootstrap alternative: https://ninna-ui.dev/alternative/bootstrap
- Bulma alternative: https://ninna-ui.dev/alternative/bulma
- Ant Design alternative: https://ninna-ui.dev/alternative/ant-design
- Flowbite alternative: https://ninna-ui.dev/alternative/flowbite
- Preline UI alternative: https://ninna-ui.dev/alternative/preline
- React component library: https://ninna-ui.dev/react-component-library
- Next.js component library: https://ninna-ui.dev/nextjs-component-library
- React Router component library: https://ninna-ui.dev/react-router-component-library
- Vite component library: https://ninna-ui.dev/vite-component-library
- Remix component library: https://ninna-ui.dev/remix-component-library
- Component docs (example): https://ninna-ui.dev/primitives/button
- Full component API reference: https://ninna-ui.dev/llms-full.txt

## Links

- Website: https://ninna-ui.dev
- GitHub: https://github.com/ninna-ui/ninna-ui
- npm: https://www.npmjs.com/org/ninna-ui