# @hero-design/rn

## Overview

`@hero-design/rn` is a React Native component library built with TypeScript and Emotion. It provides UI components, theming system, chart components (D3.js), form components, mobile-specific components (FAB, BottomSheet, Swipeable), and platform-specific implementations (iOS/Android) following Hero Design's design system principles.

## Installation

```sh
yarn add @hero-design/rn
```

**Peer Dependencies:**

```sh
yarn add react@18.3.1 react-native@0.77.3
yarn add @hero-design/react-native-month-year-picker@^8.43.2
yarn add @ptomasroos/react-native-multi-slider@^2.2.2
yarn add @react-native-community/datetimepicker@^3.5.2
yarn add @react-native-community/slider@^4.5.1
yarn add react-native-gesture-handler@~2.20.2
yarn add react-native-linear-gradient@^2.8.3
yarn add react-native-pager-view@^6.7.0
yarn add react-native-safe-area-context@^4.7.0
yarn add react-native-svg@^15.11.2
yarn add react-native-vector-icons@^9.1.0
yarn add react-native-webview@^13.10.2
```

**Requirements:**
- React 18.3.1
- React Native 0.77.3
- Node.js >= 20.0.0 (20.x or 22.x supported)
- Yarn >= 4.0.2 (enabled via Corepack: `corepack enable`)
- iOS Simulator or Android Emulator:
  - **For visual tests compatibility**: iPhone 14 (iOS 18+) or Android Pixel 6 (API 30) are recommended
  - **For non-visual fixes or demo purposes**: Any device frame with compatible OS version is sufficient

## Usage

### Basic Setup

Wrap your application with `HeroDesignProvider` to enable theming, localization, and component features (Toast, Portal):

```tsx
import React from 'react';
import { HeroDesignProvider, getTheme, Button, Card, Typography } from '@hero-design/rn';

function App() {
  const theme = getTheme();
  
  return (
    <HeroDesignProvider theme={theme}>
      <Card>
        <Typography.Title>Welcome to Hero Design</Typography.Title>
        <Button text="Get Started" intent="primary" onPress={() => {}} />
      </Card>
    </HeroDesignProvider>
  );
}
```

## Theming

Hero Design React Native uses a powerful theming system built on Emotion.

### Using ThemeSwitcher

For product-specific themes, use `ThemeSwitcher` which provides a predefined theme. Available theme names: `ehWork`, `ehJobs`, `ehWorkDark`.

```tsx
import { ThemeSwitcher } from '@hero-design/rn';

function App() {
  return (
    <ThemeSwitcher name="ehWork">
      {/* Your app */}
    </ThemeSwitcher>
  );
}
```

**Note:** `ThemeSwitcher` only provides theme. For Toast, Portal, and Locale features, use `HeroDesignProvider` with a theme from `getTheme()`.

### Design Tokens

The theme includes semantic design tokens organized by category:

- **Colors**: Global colors (`defaultGlobalSurface`, `onDefaultGlobalSurface`, etc.) and brand colors (`primary`, `secondary`, etc.)
- **Typography**: `theme.fontSizes`, `theme.fonts`, `theme.lineHeights`
- **Spacing**: `theme.space` - Consistent spacing scale (`small`, `medium`, `large`, etc.)
- **Shadows**: `theme.shadows` - Elevation and depth
- **Components**: Component-specific theme configurations via `theme.__hd__`

For comprehensive design token documentation, visit the [Mobile Design Tokens](https://design.employmenthero.com/mobile/mobile-design-tokens).

## Examples

For comprehensive examples and component documentation:

- **Documentation Site**: Visit the [Hero Design documentation site](https://design.employmenthero.com/mobile/intro)
- **Mobile Playground**: Explore the [rn-playground](https://github.com/Thinkei/hero-design/tree/master/apps/rn-playground)

## Contributing

Contributions to `@hero-design/rn` are welcome!

To get started:

1. Clone the repository: `git clone git@github.com:Thinkei/hero-design.git`
2. Enable Corepack: `corepack enable`
3. Install dependencies: `yarn install`
4. Build the package: `yarn turbo run build --filter=@hero-design/rn`
5. Run the playground: `yarn dev:rn`

**Note:** An Expo account is required to start the playground. Contact the Hero Design team for access.

For detailed contributing guidelines, see the main repository [Contributing documentation](https://design.employmenthero.com/mobile/Contributing/coContribution).