npm package: @ninna-ui/primitives
Description: 14 primitive React UI components for Ninna UI - Button, Badge, Avatar, Text, Heading, Link, Code, Kbd, Divider, and more. Accessible, themeable, Tailwind CSS v4.
Author: Ninna-UI Team
Latest version: 0.5.0

# @ninna-ui/primitives

> **15 essential React UI building blocks** - accessible buttons, typography, badges, avatars, and more. Pure React with zero Radix dependency, `forwardRef` on every component, and full Tailwind CSS v4 theming.

[![npm](https://img.shields.io/npm/v/@ninna-ui/primitives.svg)](https://www.npmjs.com/package/@ninna-ui/primitives)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)

📖 **[Full Documentation →](https://www.ninna-ui.dev/primitives)** &nbsp;|&nbsp; 📦 **[npm →](https://www.npmjs.com/package/@ninna-ui/primitives)** &nbsp;|&nbsp; 🐙 **[GitHub →](https://github.com/ninna-ui/ninna-ui/tree/main/packages/primitives)**

The foundational component set of [Ninna UI](../../README.md) - the building blocks every React app needs. Simple, accessible, and composable. Every component ships with `forwardRef`, `className` merging, `data-slot` targeting for surgical CSS overrides, and `focus-visible` keyboard accessibility out of the box.

**Pure React - no Radix dependency.** Lightweight, stateless, and tree-shakeable.

## Installation

```bash
pnpm add @ninna-ui/primitives @ninna-ui/core
```

## CSS Setup

```css
@import "tailwindcss";
@import "@ninna-ui/core/theme/presets/default.css";

@variant dark (&:is(.dark *));
```

## HTML Setup

Add the `data-theme` attribute to your `<html>` element:

```html
<html data-theme="default">
```

## Components

| Component | Description | Variants | Colors | Sizes |
|-----------|-------------|----------|--------|-------|
| `Button` | Primary action element | solid, soft, outline, ghost, text | 8 | 5 |
| `IconButton` | Icon-only button | solid, soft, outline, ghost | 8 | 5 |
| `Badge` | Status/count indicator | solid, soft, outline | 8 | 3 |
| `Avatar` | User image with fallback | - | 8 | 5 |
| `AvatarGroup` | Grouped avatar stack | - | - | - |
| `Text` | Paragraph/span text | - | - | 8 sizes |
| `Heading` | h1–h6 with consistent scale | - | - | 8 sizes |
| `Link` | Styled anchor element | - | - | - |
| `LinkOverlay` / `LinkBox` | Clickable card pattern | - | - | - |
| `Code` | Inline code highlight | solid, soft, outline, ghost | 8 | 3 |
| `Blockquote` | Styled quotation block | bordered, filled, plain | 8 | - |
| `List` / `ListItem` | Ordered/unordered lists | - | - | - |
| `Kbd` | Keyboard shortcut indicator | - | - | 3 |
| `Mark` | Highlighted text | - | 8 | - |
| `Divider` | Horizontal/vertical separator | solid, dashed, dotted | 8 | 3 weights |

## Quick Start

```tsx
import { Button, Badge, Heading, Text, Avatar } from "@ninna-ui/primitives";

function Hero() {
  return (
    <div>
      <Badge color="primary" variant="soft">New</Badge>
      <Heading as="h1" size="4xl">Welcome</Heading>
      <Text size="lg" className="text-base-content/70">
        Build beautiful interfaces with Ninna UI
      </Text>
      <Button color="primary" size="lg">Get Started</Button>
    </div>
  );
}
```

## All Exports

```typescript
import {
  Button, type ButtonProps,
  IconButton, type IconButtonProps,
  Badge, type BadgeProps,
  Avatar, AvatarGroup, type AvatarProps, type AvatarGroupProps,
  Text, type TextProps,
  Heading, type HeadingProps,
  Link, type LinkProps,
  LinkOverlay, LinkBox, type LinkOverlayProps, type LinkBoxProps,
  Code, type CodeProps,
  Blockquote, type BlockquoteProps,
  List, ListItem, type ListProps, type ListItemProps,
  Kbd, type KbdProps,
  Mark, type MarkProps,
  Divider, type DividerProps,
} from "@ninna-ui/primitives";
```

## Accessibility

Every primitive includes:
- **`forwardRef`** + `displayName` on all components
- **`data-slot`** attributes for surgical CSS targeting
- **`focus-visible`** ring styles for keyboard users
- **`className`** prop always accepted and applied last via `cn()`
- **ARIA attributes** where applicable

## Related Packages

- [`@ninna-ui/core`](../core/README.md) - Design tokens and theme presets (required)
- [`@ninna-ui/layout`](../layout/README.md) - Layout components (Box, Stack, Grid)
- [`@ninna-ui/feedback`](../feedback/README.md) - Feedback components (Alert, Toast, Loading)
- [All packages](../../README.md#packages) - Complete package list

## License

[MIT](../../LICENSE)