@starbemtech/react-native-starsystem

Cross-platform React Native UI toolkit — Starbem's design system for mobile apps.

---

Table of Contents

• Overview
• Requirements
• Installation
• Peer Dependencies
• Quick Start
• Theming
• Components
• Utilities
• TypeScript
• Contributing
• Changelog
• License

---

Overview

@starbemtech/react-native-starsystem is the official React Native UI library for the Starbem design system (Star System). It provides a set of themeable, accessible components ready for iOS and Android, built on top of React Native's core primitives.

• Full TypeScript support with exported prop types
• Theming via ThemeProvider — override any token globally
• Consistent design language aligned with the Star System Figma DS
• Compatible with React Native >= 0.64 and React >= 17

---

Requirements

Dependency	Minimum version
Node.js	>= 18
React Native	>= 0.64
React	>= 17
TypeScript (optional)	>= 5.0

---

Installation

# pnpm (recommended)
pnpm add @starbemtech/react-native-starsystem

# npm
npm install @starbemtech/react-native-starsystem

# yarn
yarn add @starbemtech/react-native-starsystem

---

Peer Dependencies

Install the required peer dependencies in your project:

pnpm add react-native-vector-icons react-native-safe-area-context

react-native-vector-icons

Follow the official linking guide for iOS and Android.

react-native-safe-area-context

Wrap your app root with SafeAreaProvider:

import { SafeAreaProvider } from 'react-native-safe-area-context';

export default function App() {
  return (
    <SafeAreaProvider>
      {/* your app */}
    </SafeAreaProvider>
  );
}

Font — Funnel Display

Star System uses Funnel Display (Google Fonts) as the brand typeface, in weights Light/Regular/Medium/SemiBold/Bold (300–700). The .ttf files ship inside this package at assets/fonts/ with a react-native.config.js declaring them — you don't need to download or copy anything yourself.

Just run the link step in your app, not in this library, so the community CLI autolinks font assets from every installed dependency (including this one):

npx react-native-asset

This copies the files into android/app/src/main/assets/fonts/ and registers them in Info.plist (UIAppFonts) for you. Rebuild the native app afterwards (pod install on iOS if needed) for the fonts to show up.

Component styles reference the fonts via fontFamily, using each weight's PostScript name (e.g. FunnelDisplay-Medium) rather than a single family + fontWeight, since iOS doesn't reliably resolve style linking across weights of one family. See src/config/fonts.tsx (fontWeights) for the full mapping.

If the font isn't linked, React Native falls back to the system default font silently — no error, no crash. If text still looks off after linking, check that the native project actually rebuilt (font registration doesn't hot-reload).

---

Quick Start

import React from 'react';
import { View } from 'react-native';
import { Button, Text, ThemeProvider } from '@starbemtech/react-native-starsystem';

export default function App() {
  return (
    <ThemeProvider>
      <View style={{ flex: 1, justifyContent: 'center', padding: 24 }}>
        <Text h3>Hello, Star System</Text>
        <Button
          title="Get Started"
          onPress={() => console.log('pressed')}
        />
      </View>
    </ThemeProvider>
  );
}

---

Theming

Wrap your app with ThemeProvider to apply a custom theme. Every component reads from the theme context, so a single override propagates to all components.

import { ThemeProvider } from '@starbemtech/react-native-starsystem';

const theme = {
  colors: {
    primary: '#FF6B19',
    secondary: '#FF3F72',
  },
  Button: {
    raised: true,
  },
};

export default function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* children */}
    </ThemeProvider>
  );
}

useTheme hook

import { useTheme } from '@starbemtech/react-native-starsystem';

function MyComponent() {
  const { theme, updateTheme } = useTheme();
  return <View style={{ backgroundColor: theme.colors.primary }} />;
}

makeStyles

import { makeStyles } from '@starbemtech/react-native-starsystem';

const useStyles = makeStyles((theme) => ({
  container: {
    backgroundColor: theme.colors.primary,
    borderRadius: 8,
  },
}));

function MyComponent() {
  const styles = useStyles();
  return <View style={styles.container} />;
}

---

Components

Component	Description
AnimatedImage	Image with entrance animation via react-native-animatable
AnimatedText	Text with entrance animation
AnimatedView	View with entrance animation
Avatar	User avatar with image, icon, or initials fallback
Badge	Numeric or status badge, composable with Avatar
BottomSheet	Modal bottom sheet overlay
Button	Solid, outline, and clear variants with loading state
Card	Surface container with optional image, title, and divider
CheckBox	Accessible checkbox with custom icon support
ContentBox	Padded content container
Divider	Horizontal line separator
Header	App navigation header with left/center/right slots
Icon	Icon from any react-native-vector-icons pack
Image	Image with placeholder and fade-in transition
Input	Text input with label, error state, and left/right icons
LinearProgress	Determinate and indeterminate progress bar
ListItem	Row item with accordion and swipeable variants
Switch	Toggle switch
Tab	Tab bar with active indicator
TabView	Swipeable tab view container
Text	Typography component with h1–h4 and paragraph variants

---

Utilities

import {
  colors,                 // default color palette
  fonts,                  // default font definitions
  normalize,              // scale text size across screen densities
  getStatusBarHeight,     // safe status bar height (iPhoneX-aware)
  getBottomSpace,         // safe bottom space (iPhoneX-aware)
  isIphoneX,              // boolean device check
  ifIphoneX,              // conditional value helper
  getIconType,            // resolve icon set by name
  registerCustomIconType, // register a custom icon set
  withBadge,              // HOC to wrap any component with a Badge
  withTheme,              // HOC to inject theme into any component
} from '@starbemtech/react-native-starsystem';

---

TypeScript

All components export their prop types. Import them directly:

import type {
  AnimatedProps,
  AvatarProps,
  BadgeProps,
  BottomSheetProps,
  ButtonProps,
  CardProps,
  CheckBoxProps,
  Colors,
  ContentBoxProps,
  DividerProps,
  FullTheme,
  HeaderProps,
  IconProps,
  ImageProps,
  InputProps,
  LinearProgressProps,
  ListItemAccordionProps,
  ListItemProps,
  ListItemSwipeableProps,
  ReplaceTheme,
  SwitchProps,
  TabItemProps,
  TabProps,
  TabViewProps,
  TextProps,
  Theme,
  ThemeProps,
  UpdateTheme,
} from '@starbemtech/react-native-starsystem';

---

Contributing

Contributions are welcome — bug reports, documentation improvements, and pull requests.

Reporting a bug

Open an issue on GitHub Issues and include:

• @starbemtech/react-native-starsystem version
• React Native and React versions
• Platform (iOS / Android) and OS version
• Minimal code to reproduce the issue
• Expected vs. actual behavior

Submitting a pull request

1. Fork the repository and create a branch:

   git checkout -b feat/your-feature-name

2. Install dependencies (requires Node >= 18 and pnpm >= 9):

   pnpm install

3. Make your changes, then verify:

   pnpm build   # must produce zero TypeScript errors
   pnpm test    # all tests must pass
   pnpm lint    # no lint errors

4. Open a PR against main describing what changed and why.

Guidelines

• All new components must be written in TypeScript and export their prop types from src/index.ts.
• Do not introduce new runtime dependencies without prior discussion.
• any casts are only acceptable for documented third-party type conflicts — add an inline comment explaining the reason.
• Keep PRs focused. One concern per PR is easier to review and revert if needed.

---

Changelog

See CHANGELOG.md for the full release history.

---

License

MIT © Starbem