Nimbus Native UI Kit

A lightweight collection of production-ready React Native components built with consistent design tokens and deep theme support. This package ships TypeScript sources, typed builds, and theming utilities so you can drop it into any React Native app and immediately benefit from polished UI primitives such as Button, TextInput, Avatar, and more.

Installation

yarn add @nimbus_sg/native-uikit
# or
npm install @nimbus_sg/native-uikit

The library depends on react-native-vector-icons. If your React Native project does not already have it installed, follow the setup instructions from its README (font linking steps vary by platform).

Quick Start

Wrap your app (or a screen subtree) in the provided ThemeProvider, render components, and customize props as needed:

import React from 'react'
import {
  ThemeProvider,
  Button,
  Text,
  Spacer,
  TextInput,
  DefaultTheme,
  ThemeOverrides,
} from '@nimbus_sg/native-uikit'

const customTheme: ThemeOverrides = {
  colors: {
    primary: {
      ...DefaultTheme.colors.primary,
      500: '#6b4eff',
    },
  },
  components: {
    button: {
      borderRadius: 16,
      padding: { vertical: 12, horizontal: 20 },
    },
  },
}

export default function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <Text size="lg" fontWeight="semibold">
        Welcome 👋
      </Text>
      <Spacer size={16} />
      <TextInput placeholder="Email" />
      <Spacer size={12} />
      <Button title="Continue" />
    </ThemeProvider>
  )
}

If no ThemeProvider is mounted the components fall back to the built-in DefaultTheme, so you can adopt the library incrementally.

Components

The package exposes each component from src via the root export. Commonly used components include:

• Avatar
• Badge
• Button
• Divider
• Icon
• Image
• ListItem
• SecureTextInput
• Spacer
• Text
• TextInput

Utilities such as useTheme, helpers for composing icon nodes, and the full Theme type are also exported.

Theming & Customization

The ThemeProvider accepts a ThemeOverrides object. Each field is optional and only overrides the portion you provide:

type ThemeOverrides = {
  colors?: Partial<Color>
  fontSize?: Partial<Theme['fontSize']>
  avatarSizes?: Partial<Theme['avatarSizes']>
  fontFamily?: Partial<NonNullable<Theme['fontFamily']>>
  components?: Partial<{
    avatar: { borderRadius?: number; padding?: number | { vertical?: number; horizontal?: number } }
    button: { ... }
    // input, secureTextInput, badge, icon, image
  }>
}

• Color palette – Every color swatch (primary, neutral, danger, etc.) is exposed so you can align the kit with your brand colors.
• Typography – Override global font sizes or provide a fontFamily map with regular, bold, medium, and semibold faces.
• Avatar sizing – Adjust named sizes to match your design system.
• Component tokens – Each component listed in Theme.components supports independent borderRadius and padding, letting you globally fine-tune corners and spacing without touching individual props.

Use the useTheme() hook inside your code to access the merged theme if you build custom components on top of this UI kit.

Example App

Inside /example you'll find an Expo project that consumes the package directly from the local workspace. It demonstrates:

• Linking custom fonts and feeding them to the theme
• Overriding component-level padding/border radius
• Mixing icons, badges, spacers, and images in a realistic layout

Run it with:

cd example
yarn
yarn expo start

Contributing

See the contributing guide for instructions on setting up the repo, running tests (yarn test), linting (yarn lint), and submitting PRs. The project uses react-native-builder-bob for packaging, so remember to run yarn prepack before publishing.

License

MIT © Nimbus