# RootNative UI

> Design-system agnostic component library for React Native — ships with Material Design 3 out of the box

RootNative UI (`@rootnative`) is a React Native component library with a pluggable theme engine. It ships with Material Design 3 as the default design system but supports custom design systems via `BaseTheme`, `ThemeProvider`, and `defineTheme`.

## Packages

- `@rootnative/core`: Theme engine (`BaseTheme`, `ThemeProvider`, `defineTheme`, `useTheme`), MD3 preset (`material`, light/dark themes), responsive breakpoint hooks
- `@rootnative/utils`: Shared utilities — color helpers (`alphaColor`, `blendColor`), elevation styles, RTL support, icon resolver. Test helper via `@rootnative/utils/test`.
- `@rootnative/components`: UI components (Avatar, Button, ButtonGroup, IconButton, AppBar, Card, Chip, Checkbox, Radio, Slider, Progress, Switch, TextField, Typography, Layout, List, Portal, KeyboardAvoidingWrapper)
- `@rootnative/icons`: Icon-library adapters — `createLucideResolver`, `createPhosphorResolver`, `createVectorIconsResolver`, `withLegacyMdiFallback`. Lucide / Phosphor / `@expo/vector-icons` are optional peer deps.

## Quick start

### New project

```bash
npx rootnative create my-app
cd my-app
npx expo start
```

The `create` command scaffolds a ready-to-run Expo project with `ThemeProvider` and example components pre-configured. It prompts for project name, display name, and package manager.

### Existing project

```bash
pnpm add @rootnative/core @rootnative/utils @rootnative/components @expo/vector-icons react-native-safe-area-context react-native-svg react-native-reanimated react-native-worklets
```

Wrap root with provider:
```tsx
import { ThemeProvider } from '@rootnative/core'

export default function App() {
  return (
    <ThemeProvider>
      {/* Your app */}
    </ThemeProvider>
  )
}
```

Import components via subpath exports (preferred for tree-shaking):
```tsx
import { Button } from '@rootnative/components/button'
import { Card } from '@rootnative/components/card'
```

Or from root:
```tsx
import { Button, Card } from '@rootnative/components'
```

## Requirements

- React Native 0.81+, React 19+, Expo SDK 54+
- Peer deps: `react-native-safe-area-context >=4`, `react-native-reanimated >=4`, `react-native-worklets >=0.5`, `react-native-svg >=15` (CircularProgress)
- Optional peer dep: `@expo/vector-icons >=14` (only needed if you plan to use icons)
- `@material/material-color-utilities >=0.4` (required peer of `@rootnative/core`, used by `createMaterialTheme`)
- All component peers are declared optional, so NO package manager auto-installs them (npm/pnpm only auto-install required peers; Yarn classic installs none). Install the full list above explicitly.

`react-native-reanimated` powers state-layer transitions and gesture-driven components (Slider, Switch). Required for any interactive component; safe to skip only if you use Typography/Layout/Portal/KeyboardAvoidingWrapper exclusively. Bundled with Expo SDK 54 and works in Expo Go.

Reanimated 4 runs on `react-native-worklets` (installed above). Expo SDK 54 bundles its Babel plugin — nothing to configure. On bare React Native, add `'react-native-worklets/plugin'` last in `babel.config.js` plugins.

## Docs

- Full docs: https://rootnative.github.io/ui/
- For AI agents (all LLM-doc locations + CLAUDE.md snippet): https://rootnative.github.io/ui/llms
- Installation: https://rootnative.github.io/ui/installation
- Theming: https://rootnative.github.io/ui/theming
- Components: https://rootnative.github.io/ui/components/button

## CLI

```bash
npx rootnative create                    # Scaffold a new project (interactive)
npx rootnative create my-app             # Scaffold with name
npx rootnative create my-app -y          # Non-interactive (defaults)
npx rootnative create -t with-router     # Use router template
npx rootnative init                      # Initialize existing project for CLI workflow
npx rootnative add button card           # Copy component source into your project
npx rootnative update                    # Update installed components
npx rootnative upgrade                   # Upgrade @rootnative/core + install new peer deps
npx rootnative list                      # List available components
npx rootnative doctor                    # Check project health
```

All commands that install packages accept `--package-manager <pm>` to override auto-detection (`npm`, `yarn`, `pnpm`, `bun`).

The `create` command is the fastest way to start a new project. The `init` + `add` workflow is for adding components as source files to an existing project (copy-paste workflow, similar to shadcn/ui).

## Full API reference

- [llms-full.txt](https://rootnative.github.io/ui/llms-full.txt): Complete API reference with all component props, types, and usage examples in a single file optimized for LLM consumption.

## Per-package LLM docs

Each published npm package ships its own `llms.txt` for AI tools to read from `node_modules`:

- `@rootnative/core` → `node_modules/@rootnative/core/llms.txt` (theme system API + types)
- `@rootnative/components` → `node_modules/@rootnative/components/llms.txt` (all component props)
- `@rootnative/icons` → `node_modules/@rootnative/icons/llms.txt` (Lucide / Phosphor / vector-icons adapters)
- `@rootnative/cli` → `node_modules/@rootnative/cli/llms.txt` (CLI commands)