npm package: @nimbus_sg/native-uikit
Description: test
Author: Nimbus
Latest version: 0.5.6

# 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

```bash
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:

```tsx
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:

```ts
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:

```bash
cd example
yarn
yarn expo start
```

## Contributing

See the [contributing guide](CONTRIBUTING.md) for instructions on setting up the repo, running tests (`yarn test`), linting (`yarn lint`), and submitting PRs. The project uses [react-native-builder-bob](https://github.com/callstack/react-native-builder-bob) for packaging, so remember to run `yarn prepack` before publishing.

## License

MIT © Nimbus