Getting Started with React Native

Follow these instructions to use Blueprint components (📦@hover/design-system-react-native) in a React Native application.

Installation

Info
Ensure you have read credentials for npm packages namespaced with @hover

yarn add @hover/design-system-react-native

Usage

To use the design system you have to ensure two things:

Your application is wrapped with the DesignSystemProvider provider.
You're loading Hover's custom Diatype font variant into your app.

import { Body, DesignSystemProvider } from '@hover/design-system-react-native';
const App = () => (
  <DesignSystemProvider>
    <Body>Hello world!</Body>
  </DesignSystemProvider>
);

Technical Details

Tamagui

We built the React Native version of our design system on top of Tamagui, a framework designed specifically to build universal component libraries.

We leverage as much of it as we can and, before implementing anything custom from scratch, default to building on top what already is available.

Primitives

The primitives we expose on the design system should be enough for anyone to build any layout variation in any of our Figma files. They consist of a few:

Heading and Body to render any type of text.
Stack (along with XStack and YStack) to build any visual "box" (think of a token-aware View).

Design Tokens

Design tokens are variables that store design-related values such as colors, typography, spacing, and more. They serve as the single source of truth for the design system, ensuring consistency across all platforms and codebases.

By centralizing design values into tokens, we can easily update the look and feel of your application by modifying the token values in a single place. This approach promotes consistency, maintainability, and collaboration between designers and developers.

Styling

All of our primitives implement styling via props. Any styling prop available in React Native is available and the values are read directly from our design tokens, making it easy to implement UIs that look consistent across the board, avoiding any type of guess work when it comes to what values should be used for a given property and most importantly, completely eliminating the need for magic numbers.

import { Stack, Heading, Body } from '@hover/design-system-react-native';
const App = () => (
  <Stack borderRadius="$round" backgroundColor="$brandGreen" padding="$300">
    <Body>I am a box with round corners!</Body>
  </Stack>
);

All tokens are camel case, prefixed with $ and followed by their alias, which could be a name such as $round or a number such as $300.

We ship types with the library which should give you auto completion for all available values in your text editor/IDE.

Always use tokens when styling! If for whatever reason you find yourself needing something that isn't available via tokens, do reach out to us on Slack and mark us in your pull requests so we are aware of your use case and can help guide you.

// Nope
<Stack padding={40} backgroundColor="#4a3d5d"  />
// Yes 👍
<Stack padding="$size700" backgroundColor="$brandPurple800"  />

Theming

The design system comes with basic light and dark theming support. The default theme is light but there's also a dark theme that can be used on an entire page or just portions of it.

Tip
Check out the Theming story in Storybook to see how themes work in practice

The way you activate a theme is by wrapping it with the Theme component, passing the name of the theme as a prop.

import {
  Button,
  DesignSystemProvider,
  Theme,
} from '@hover/design-system-react-native';
const App = () => (
  <DesignSystemProvider>
    <Button>Light button</Button>
    <Theme name="dark">
      <Button>Dark button</Button>
    </Theme>
    <Button themeInverse>Also a dark button</Button>
  </DesignSystemProvider>
);

This can be useful in situations where you need a section of the app to behave like dark mode, but not the entire screen which is a fairly common pattern to see in our designs.

In React Native we still do not have any specification or requirements to support full global dark theme yet, so if you find yourself in a situation where this is being asked of you, please reach out to us.

Info
Be aware that not all components support dark mode yet

Contributing

The project has been started and is actively maintained by Rafael Rinaldi and Rodrigo Siqueira from the Mobile Core team but everybody is welcome to contribute.

If you are considering contributing, follow these guidelines:

Before adding something new, please ping #design-system on Slack with your proposal.
Ensure the Figma file with all components contains specs for the component you are proposing.
When implementing a new component, first check if Tamagui doesn't already have something similar we can reuse.
Only merge your PR if either one of the main maintainers have had a chance to review your work.
Add tests and stories to your implementation.
If your component requires adding new tokens, do so as a separate PR first.

Storybook

A nice visual list of all components available in the design system are available via Storybook. You can run the following from the root of the repository to spin up a dev server and then preview it in a device, simulator or in the browser:

# Open Storybook via Expo Go on the iOS simulator
yarn rp storybook-react-native storybook:ios -c

If you are working on making changes to the design system you can also run the following as a separate process, so files automatically recompile on change giving you live previews in Storybook:

yarn preconstruct watch