@boostdev/design-system-react-native

BoostDev React Native component library: accessible, token-driven components built on @boostdev/design-system-foundation.

Install

npm install @boostdev/design-system-react-native
# or
pnpm add @boostdev/design-system-react-native

Peer dependencies:

• react >= 18
• react-native >= 0.70
• @boostdev/design-system-foundation >= 2.0.0
• @react-navigation/native >= 6.0.0 (optional — only needed if you use the React Navigation bridge below)

Standalone usage

The library is fully self-contained. Wrap your app in ThemeProvider and use components directly — no other dependencies required.

import { ThemeProvider, Button, Typography } from '@boostdev/design-system-react-native';

export default function App() {
  return (
    <ThemeProvider>
      <Typography>Hello</Typography>
      <Button onPress={() => {}}>Press me</Button>
    </ThemeProvider>
  );
}

ThemeProvider auto-detects the system color scheme (light/dark) via useColorScheme, or you can pass colorScheme="light" | "dark" to force one. Inside the tree, useTheme() exposes { colors, isDark } where colors is the full foundation token palette (colorBg, colorOnBg, colorInteractive, …).

Brand theming (token overrides)

Override any semantic color per scheme — the React Native equivalent of the web boostdev.tokens.override CSS layer. One prop recolors every component and useReactNavigationTheme:

import { ThemeProvider } from '@boostdev/design-system-react-native';

<ThemeProvider
  tokens={{
    light: { colorInteractive: '#00c853', colorInteractiveOnBg: '#2d5a1e' },
    dark:  { colorInteractive: '#00c853', colorInteractiveOnBg: '#a8d48a' },
  }}
>
  <App />
</ThemeProvider>;

Unspecified tokens keep their foundation values. Available token names are the keys of colors.light from @boostdev/design-system-foundation/native (colorBg, colorInteractive, colorError, …) — see the ThemeColorName type.

Pass a stable tokens reference (a module-level constant, not an inline object literal) — the provider memoizes the merged colors on that reference.

React Navigation compatibility

The library also ships a thin, opt-in bridge that produces a React Navigation Theme from the same foundation tokens. The bridge is purely additive — nothing about the standalone API changes when you use it, and @react-navigation/native is only required if you actually consume the bridge.

Hook variant — when you wrap in ThemeProvider

import { NavigationContainer } from '@react-navigation/native';
import { ThemeProvider, useReactNavigationTheme } from '@boostdev/design-system-react-native';

function NavRoot({ children }) {
  const theme = useReactNavigationTheme();
  return <NavigationContainer theme={theme}>{children}</NavigationContainer>;
}

export default function App() {
  return (
    <ThemeProvider>
      <NavRoot>{/* screens */}</NavRoot>
    </ThemeProvider>
  );
}

useReactNavigationTheme() reads from our ThemeProvider and reflects light/dark switches automatically. It accepts optional { colors, fonts } overrides.

Builder variant — standalone or outside React

import { NavigationContainer } from '@react-navigation/native';
import { createReactNavigationTheme } from '@boostdev/design-system-react-native';

const theme = createReactNavigationTheme({ dark: false });

<NavigationContainer theme={theme}>{/* … */}</NavigationContainer>;

createReactNavigationTheme(options) is a pure function. Use it when you do not wrap in ThemeProvider, or when you need a theme outside React (tests, navigators created at module scope, etc.).

Options:

| Option | Type | Description | | -------- | ----------------------------------- | ------------------------------------------------------------------------ | | dark | boolean | Selects the dark token set. Default false. | | tokens | colors.light \| colors.dark shape | Bring your own foundation token set. Defaults to colors[dark ? 'dark' : 'light'] from the foundation. | | colors | Partial<ReactNavigationThemeColors> | Override individual Navigation colors (e.g. { primary: '#ff0' }). | | fonts | Partial<ReactNavigationThemeFonts> | Override individual Navigation font styles. |

Token mapping

The bridge maps foundation tokens to React Navigation's six-color palette. The mapping lives in this repo (src/native/ReactNavigationTheme.ts) — the foundation package stays generic.

| React Navigation | Foundation token | | ---------------- | --------------------------------------------- | | primary | colorInteractive | | background | colorBg | | card | colorBgSubtle | | text | colorOnBg | | border | palette.grey200 (light) / grey700 (dark) | | notification | colorError |

Fonts use font.family.body with weights from font.weight (body, medium, bold, heading).

Override any of these per-call via the colors / fonts options without changing the foundation.

Custom themes

Both standalone (useTheme) and Navigation (useReactNavigationTheme / createReactNavigationTheme) consume the same foundation tokens. To build a custom theme:

1. Author a token set matching the foundation's colors.light / colors.dark shape.
2. Pass it as tokens to createReactNavigationTheme({ tokens, dark }) for the Navigation layer.
3. For the standalone layer — and to have overrides flow through to the Navigation theme automatically — use the tokens prop on ThemeProvider (see Brand theming above).

Development

pnpm install
pnpm build        # tsup → dist/
pnpm typecheck    # tsc --noEmit
pnpm test         # vitest (uses react-native-web alias)

License

ISC © Boostdev