# 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

## Documentation

- Landing page: https://ninna-ui.dev/
- Introduction: https://ninna-ui.dev/docs
- Examples hub: https://ninna-ui.dev/examples
- Example - Authentication Login: https://ninna-ui.dev/examples/authentication-login
- Example - Dashboard: https://ninna-ui.dev/examples/dashboard
- Example - Settings Page: https://ninna-ui.dev/examples/settings-page
- Example - User Profile: https://ninna-ui.dev/examples/user-profile
- Example - Hero Header: https://ninna-ui.dev/examples/hero-header
- Example - Features Grid: https://ninna-ui.dev/examples/features-grid
- Example - Pricing Table: https://ninna-ui.dev/examples/pricing-table
- Example - FAQ Section: https://ninna-ui.dev/examples/faq-accordion
- Example - Contact Form: https://ninna-ui.dev/examples/contact-form
- Example - Error 404: https://ninna-ui.dev/examples/error-404
- Example - Article Cards: https://ninna-ui.dev/examples/article-cards
- Example - Article Page: https://ninna-ui.dev/examples/article-page
- 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