RNUI

RNUI is a React Native UI kit built as a layered monorepo: design tokens, headless hooks, and styled components with multi-brand theming.

• Design tokens — primitive → semantic → component recipes
• Headless hooks — reusable logic, accessibility, and gesture state
• Styled components — 70+ pre-built, themeable UI primitives
• Motion presets — shared animation configuration
• Multi-brand support — runtime brand and color-scheme switching

Published packages: @truongdq01/tokens, @truongdq01/headless, @truongdq01/ui, @truongdq01/themes.

Repository: github.com/truongnat/rnui

Package status

Package	Version	Description
@truongdq01/tokens	1.0.3	Design tokens (primitive, semantic, component, motion)
@truongdq01/headless	1.0.3	ThemeProvider, theme hooks, and headless behavior hooks
@truongdq01/ui	1.0.3	Styled React Native components
@truongdq01/themes	1.0.3	Multi-brand color presets
@truongdq01/example	0.0.2	Expo example app (not published)

CI on develop runs build, lint, typecheck (library packages + example app shell), and tests. See .github/workflows/ci.yml.

Example typecheck covers the example app shell (index + shared helpers); per-component showcase screens are checked separately via bun run typecheck:showcases in apps/example (known API drift — see checklist).

Target environment

RNUI currently targets modern React Native apps:

Requirement	Version
React Native	≥ 0.83
React	≥ 19
New Architecture	Recommended (project development assumes New Architecture)

RNUI currently targets modern React Native apps. If you need wider React Native version support, check compatibility before adopting.

Required peer dependencies (install in your app):

• react-native-reanimated ≥ 4.2.0
• react-native-gesture-handler ≥ 2.30.0
• react-native-worklets ≥ 0.7.0
• react-native-safe-area-context ≥ 5.6.0 (used by layout/navigation-related components)
• react-native-svg (required when using Icon and SVG-based components such as CircularProgress)
• lucide-react-native (required when using the Icon component)

Optional peer dependencies:

Package	Used by
@shopify/flash-list	Virtualized lists in Select (falls back to FlatList)
expo-blur	Native blur in GlassCard (falls back to translucent View)
expo-linear-gradient	Native gradients in Gradient (falls back when absent)

Installation

npm / bun (consumers)

npm install @truongdq01/ui @truongdq01/headless @truongdq01/tokens
# optional brand presets
npm install @truongdq01/themes

Install peer dependencies in your app (not only in a shared library package):

npm install react-native-reanimated react-native-gesture-handler react-native-worklets react-native-safe-area-context react-native-svg lucide-react-native

Expo

npx expo install @truongdq01/ui @truongdq01/headless @truongdq01/tokens
npx expo install react-native-reanimated react-native-gesture-handler react-native-worklets react-native-safe-area-context react-native-svg lucide-react-native
npx expo install expo-blur expo-linear-gradient

Optional FlashList for better list performance in Select:

npx expo install @shopify/flash-list

Usage

Wrap your app with ThemeProvider. By default it includes GestureHandlerRootView; if your app already provides one at the root, pass withGestureRoot={false}.

import { Button, Card, Input } from '@truongdq01/ui';
import { ThemeProvider } from '@truongdq01/headless';

export default function App() {
  return (
    <ThemeProvider colorScheme="system">
      <Card padding="md">
        <Input label="Email" placeholder="you@example.com" />
        <Button label="Submit" variant="solid" onPress={() => {}} />
      </Card>
    </ThemeProvider>
  );
}

If you already wrap the app with GestureHandlerRootView:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

<GestureHandlerRootView style={{ flex: 1 }}>
  <ThemeProvider withGestureRoot={false}>
    <App />
  </ThemeProvider>
</GestureHandlerRootView>

Headless hooks

Use hooks directly for custom UI while keeping RNUI behavior and accessibility:

import { usePressable } from '@truongdq01/headless';
import { GestureDetector } from 'react-native-gesture-handler';
import Animated from 'react-native-reanimated';

function PressableSurface({ onPress, children }) {
  const { gesture, animatedStyle, accessibilityProps } = usePressable({ onPress });

  return (
    <GestureDetector gesture={gesture}>
      <Animated.View style={animatedStyle} {...accessibilityProps}>
        {children}
      </Animated.View>
    </GestureDetector>
  );
}

Development

Requires Bun.

git clone https://github.com/truongnat/rnui.git
cd rnui
bun install
bun run build
bun run typecheck
bun run lint
bun run test
bun run docs

Example app

bun run demo          # Expo dev client (from repo root)
bun run demo:go       # Expo Go
cd apps/example
bun run ios
bun run android

Documentation site

bun run docs          # dev server at http://localhost:4321
bun run docs:build    # production build

See docs/README.md for docs site structure.

Architecture

@truongdq01/tokens     primitive → semantic → component tokens
        ↓
@truongdq01/headless   ThemeProvider, useTheme, behavior hooks
        ↓
@truongdq01/ui         styled components
        ↓
@truongdq01/themes     optional brand presets

Component inventory and maturity notes: Component status (also on the docs site when built).

AI-native usage

RNUI ships AI-readable metadata so coding agents generate screens with the design system — not one-off custom UI.

Resource	Purpose
.ai/rnui.manifest.json	Top-level AI entrypoint
.ai/component-registry.json	Machine-readable component catalog
.ai/design-rules.md	Layout, tokens, anti-patterns
.ai/screen-generation.md	Screen workflow and templates
.ai/prompts/	Copyable agent prompts
.ai/examples/	Reference screen implementations
AGENTS.md	Full agent instructions

Validate AI files: bun run ai:check

Example prompt:

Build a clean mobile settings screen using only RNUI components. Read .ai/rnui.manifest.json first, follow .ai/design-rules.md, and use components from .ai/component-registry.json. Do not create custom Button, Card, Input, Typography, or layout primitives.

Docs: AI usage guide (also on the docs site under Introduction → AI usage).

Scripts

Script	Description
bun run build	Build all packages
bun run dev	Watch mode (Turbo)
bun run typecheck	TypeScript check (all packages with a typecheck script)
bun run lint	Biome lint + format check
bun run test	Unit tests
bun run docs	Start docs dev server
bun run docs:build	Build docs site
bun run demo	Start Expo example app (dev client)
bun run demo:go	Start example app in Expo Go
bun run ai:check	Verify AI metadata files exist
bun run changeset	Create a changeset for release
bun run release	Build and publish (maintainers)

License

MIT © 2026 RNUI Project