# Hover Design System (React Native)

> Hover's Bauhaus design system for React Native. Built on Tamagui. All imports
> come from `@hoverinc/design-system-react-native`. Components use Tamagui token
> notation (`$400`, `$background`) and ship with light/dark theme support.

> **Working on the web build?** This file documents the React Native build
> only — see the [React/Chakra artifact](/llms.txt) instead.

## Setup

- Package: `@hoverinc/design-system-react-native`
- Underlying engine: [Tamagui](https://tamagui.dev/)
- Font: Hover Diatype (Regular, Bold, Regular-Italic, Bold-Italic)

```tsx
import {
  DesignSystemProvider,
  FontScaleProvider,
} from '@hoverinc/design-system-react-native';

function App() {
  return (
    <FontScaleProvider>
      <DesignSystemProvider>
        <YourApp />
      </DesignSystemProvider>
    </FontScaleProvider>
  );
}
```

`FontScaleProvider` supports OS-level font scaling for accessibility. Wrap the
app once, near the root.

## Design Tokens

Use Tamagui token strings as prop values — never raw pixel or hex values. Tokens
carry a `$` prefix.

### Spacing

Used for `padding`, `margin`, `gap`. The same scale also drives `width`,
`height`, and other size-shaped props.

```tsx
<View padding="$400" gap="$300" marginBottom="$500">
  …
</View>
```

### Color tokens

Always prefer **semantic** tokens — they auto-resolve light and dark mode. Only
fall back to raw color tokens (`$primary600`, `$neutral200`) when no semantic
equivalent exists.

#### Backgrounds

`$background`, `$backgroundSecondary`, `$backgroundInvert`, `$backgroundPress`,
`$backgroundDisabled`, `$backgroundWeak`, `$backgroundSecondaryInvert`

#### Text

`$color`, `$colorDimmed`, `$colorDisabled`, `$colorInvert`, `$colorPress`

#### Borders and dividers

`$borderColor`, `$borderColorPress`, `$divider`, `$selectedBorderColor`

#### Status

- Error: `$errorColor`, `$errorBackground`, `$errorAccent`
- Success: `$successColor`, `$successBackground`, `$successAccent`
- Warning: `$warningColor`, `$warningBackground`, `$warningAccent`
- Info: `$infoColor`, `$infoBackground`, `$infoAccent`

#### Glass

`$glassBackground`, `$glassColor`, `$glassAccent`, `$glassBorderStroke`,
`$glassBorderPress`, `$glassBorderHighlight`

#### Default and selected states

`$defaultAccent`, `$defaultBackground`, `$defaultColor`, `$selectedBackground`,
`$selectedColor`, `$selectedBorderColor`

For exact pixel values per token (spacing, sizes, radius, fonts), see the
per-topic detail pages under `/llms-rn/foundation/...`.

## Style Props

Always use **verbose** prop names — never Tamagui shorthand:

| Prefer                   | Avoid        |
| ------------------------ | ------------ |
| `padding`                | `p`          |
| `paddingHorizontal`      | `px`         |
| `paddingVertical`        | `py`         |
| `margin`, `marginTop`, … | `m`, `mt`, … |
| `width` / `height`       | `w` / `h`    |
| `backgroundColor`        | `bg`         |
| `borderRadius`           | `br`         |
| `alignItems`             | `ai`         |
| `justifyContent`         | `jc`         |
| `flexDirection`          | `fd`         |

## Components

All UI components are imported from `@hoverinc/design-system-react-native`.
Layout primitives are re-exported from Tamagui and follow the same import path.

### Forms and inputs

`Button`, `IconButton`, `Field`, `InputField`, `FieldSearch`, `FieldPassword`,
`TextInput`, `TextArea`, `Checkbox`, `Radio`, `RadioGroup`, `Select`,
`SelectNative`, `Toggle`, `BinaryButton`, `BinaryButtonGroup`

### Typography

`Heading`, `Body` — always use these instead of raw `<Text>` with manual font
styles.

### Layout

`Stack`, `View`, `XStack`, `YStack`, `ZStack`, `Grid`, `ScrollView`, `FlatList`,
`SectionList`

### Feedback

`Loader`, `Progress`, `Toast`

### Media

`Avatar`, `AvatarGroup`, `Icon`, `Image`, `Logo`

### Overlay

`Sheet`, `Popover`, `Menu`

### Decorative

`Shadow`, `Glass`

For each component's props, variants, and examples, see the matching detail page
under `/llms-rn/components/...`.

## Common Patterns

### Vertical stack with consistent spacing

```tsx
<YStack gap="$300" padding="$400">
  <Heading size="medium">Title</Heading>
  <Body>Description text</Body>
</YStack>
```

### Themed semantic surface

```tsx
<View backgroundColor="$backgroundSecondary" borderRadius="$300" padding="$400">
  <Body color="$colorDimmed">Secondary content</Body>
</View>
```

### Error state

```tsx
<View backgroundColor="$errorBackground" padding="$300" borderRadius="$200">
  <Body color="$errorColor">Something went wrong.</Body>
</View>
```

## Common Mistakes to Avoid

- Don't import from `style-guide/*` — always use
  `@hoverinc/design-system-react-native`
- Don't hardcode hex color values — use semantic tokens (`$color`,
  `$background`, …)
- Don't hardcode pixel values for spacing, sizes, or radius — use Tamagui tokens
  (`$400`, `$300`, …)
- Don't use `StyleSheet.create()` — use Tamagui `styled()` or apply token props
  directly
- Don't use `styled-components/native` — use Tamagui `styled()` from the design
  system
- Don't use raw `<Text>` with manual `fontSize`/`fontWeight` — use `<Body>` or
  `<Heading>` with the `size` prop
- Don't use `Box` from `style-guide/layout/Box` — use `View` or `Stack` from the
  design system
- Don't use Tamagui shorthand props (`p`, `bg`, `br`, `ai`, `jc`, `fd`) — always
  use the verbose names
- Don't nest `DesignSystemProvider` — it's a no-op; wrap once near the root

## Detailed References

- [Responsive Breakpoints](/llms-rn/foundation/tokens/breakpoints.md): Responsive breakpoint tokens for media queries etc.
- [Shadow](/llms-rn/foundation/tokens/shadow.md): Shadow and outline tokens
- [Typography](/llms-rn/foundation/tokens/typography.md): Typography tokens
- [Badge](/llms-rn/components/data-display/badge.md): Badge component
- [Toast](/llms-rn/components/feedback/toast.md): Toasts are used to show alerts on top of an overlay, usually used to give feedback to users after an action has taken place.

- [Buttons](/llms-rn/components/forms/button.md): Use buttons to let users perform key actions tied to what they see—submitting a form, opening a modal, or editing content.
- [Checkbox](/llms-rn/components/forms/checkbox.md): Checkbox component
- [Field](/llms-rn/components/forms/field.md): A comprehensive input field component for React Native with label, validation, and addon support
- [IconButton](/llms-rn/components/forms/icon-button.md): Button component that uses an icon for its label
- [Radio](/llms-rn/components/forms/radio.md): Radio component
- [Select](/llms-rn/components/forms/select.md): Select component
- [TextInput](/llms-rn/components/forms/text-input.md): Text Input component
- [Toggle](/llms-rn/components/forms/toggle.md): A toggle component to set on or off state
- [Avatar](/llms-rn/components/media/avatar.md): Display photo of a user, or their initials, on a background
- [Grid](/llms-rn/components/layout/grid.md): A responsive grid layout component for React Native
- [Menu](/llms-rn/components/overlay/menu.md): An accessible dropdown menu for the common dropdown menu button design pattern. Menu uses roving tabIndex for focus management.
- [Popover](/llms-rn/components/overlay/popover.md): Popover is a non-modal dialog that floats around a trigger.
- [Sheet](/llms-rn/components/overlay/sheet.md): A responsive overlay component optimized for mobile devices
- [Body](/llms-rn/components/typography/body.md): A typography primitiving for displaying text and paragraphs in an interface.
- [Heading](/llms-rn/components/typography/heading.md): A typography primitive for ensuring consistent heading styles and hierarchy

## Coverage Gaps

The React Native artifact does not yet cover all of the design system. See [llms-rn-gaps.md](/llms-rn-gaps.md) for the full list.

- **MDX pages without a `## React Native` section:** 86 (data-display: 5, engineering: 27, feedback: 7, forms: 8, foundation: 10, layout: 8, media: 2, navigation: 4, other: 5, overlay: 1, patterns: 8, typography: 1)
- **RN package exports without an MDX page:** 29