@argo22/mobile-ui-kit

UI Kit for expo based mobile apps. Based on react-native-unistyles and React Native Primitives .

This library follows expo ecosystem requirements. Make sure you have expo ready for development before installing this package.

If you don't have expo development ready - follow installation steps

Installation

1. Install the library with you favourite package manager

# with expo install
npx expo install @argo22/mobile-ui-kit
# with yarn
yarn add @argo22/mobile-ui-kit
# with npm
npm install @argo22/mobile-ui-kit

2. Install peer dependencies

yarn add react-native-reanimated react-native-safe-area-context react-native-svg react-native-unistyles

Setup

1. Create or extend theme - see Theming
2. In root of your project define your themes types for Typescript to work correctly

// if you defined themes
type AppThemes = {
  light: typeof lightTheme,
  dark: typeof darkTheme
}

// override library types
declare module 'react-native-unistyles' {
  export interface UnistylesThemes extends AppThemes {}
}

3. In root register your themes - details in official Unistyles setup

import { UnistylesRegistry } from 'react-native-unistyles'

UnistylesRegistry
  .addThemes({
    light: lightTheme,
    dark: darkTheme,
    // register other themes with unique names
  })
  .addConfig({
    // you can pass here optional config described below
    adaptiveThemes: true
  })

4. Add <PortalHost /> to the root of component tree. It will be used for all overlay components

export default function App() {
  return (
    <SafeAreaProvider>
      <Root />

      <PortalHost /> {/* <-- Add this */}
    </SafeAreaProvider>
  );
}

All done. You can now use @argo22/mobile-ui-kit. For API Overview see API documentation

Usage

import components from @argo22/mobile-ui-kit

import { Button } from "@argo22/mobile-ui-kit";
export default () => <Button>Button</Button>

import icons from @argo22/mobile-ui-kit/build/icons. For more information see Icons section

import { SearchIcon } from "@argo22/mobile-ui-kit/build/icons";
export default () => <SearchIcon />

API documentation

Atoms

Atoms are the fundamental building blocks of the UI, providing simple and reusable components like typography and component for custom icons.

• Card
• Helper Text
• Custom Icon
• Label
• Loader
• Typography
• UI Slot

Molecules

Molecules combine two or more atoms to form more complex UI components, such as buttons and input fields, which offer richer functionality and interaction.

• Button
• IconButton
• Check Box
• Input
• Item List
• Radio Group
• Select
• Switch

Toast

The Toast category includes components related to displaying transient notifications to inform users of important information or status changes.

• Toast
• ToastManager

Theming

UI kit offers a way to customize components and UI tokens through themes. There is defaultTheme you can use as a starting point to customize the UI kit. Use createTheme(tokensConfig, componentsCongif) to customize the default theme. If you leave createTheme() without params, the defaultTheme will be used. In other case the config will be merged with the defaultTheme values.

import { createTheme } from "@argo22/mobile-ui-kit";

const fonts = {
  paragraph: {
    light: "Nunito-Regular",
    strong: "Nunito-Bold",
  },
  heading: {
    light: "Nunito-Regular",
    strong: "Nunito-Bold",
  },
};

export const lightTheme = createTheme({
  fontFamily: fonts,
  color: {
    primary: {
      100: "#f6c7b4",
      400: "#f19068",
      500: "#f17643",
      600: "#ef6228",
      800: "#bb3d0a",
    },
  }
});

You can customize the theme as long as the structure stays the same. Make sure to use Theme type for custom themes to ensure structure integrity.

For official docs follow Unistyles theming guide

Loading Themes

Load themes in setup phase of react-native-unistyles.

import { UnistylesRegistry } from 'react-native-unistyles'
import { defaultTheme } from "./theme";

UnistylesRegistry
  .addThemes({
    light: defaultTheme,
    pumpkin: pumkinTheme,
  })

Changing Theme

Use UnistylesRuntime.setTheme() function to change a theme programmatically

import { UnistylesRuntime } from 'react-native-unistyles'

// change the theme in any component
export const ChangeTheme = () => (
    <Button
        title="Change theme"
        onPress={() => UnistylesRuntime.setTheme('pumpkin')}
    />
)

Icons

The package uses Lucide Icons as the icon set of choice and follows its design rules. Icons can be searched at Lucide Icons and imported from @argo22/mobile-ui-kit/build/icons.

Usage

To use Lucide Icons, import them from the library as shown below:

import { SearchIcon } from "@argo22/mobile-ui-kit/build/icons";
export default () => <SearchIcon />

Custom Icons

To add a custom icon, use the Icon component.

Design Guidelines for Custom Icons

Designers should adhere to the following guidelines to ensure custom icons are compatible with Lucide's style:

1. Use Lucide Icons: Always use Lucide Icons as the primary icon set. Avoid using other icon sets to maintain visual consistency.
2. Icon Dimensions: Custom icons should be designed at 24x24 pixels.
3. ViewBox: Set the viewBox attribute to 0 0 24 24.
4. StrokeWidth: Set the stroke-width to 2 to match the Lucide style guide.

By following these guidelines, you ensure that custom icons integrate seamlessly with the existing icon set and maintain a consistent design throughout the application.

Contributing

Contributions are very welcome! Please refer to guidelines described in the contributing guide.