# Theme

Canonical page: https://docs.ovok.com/native-sdk/guide/components/theme

The Theme module provides a comprehensive theming system built on Material Design 3 with custom color palettes, responsive spacing, and typography. It enables consistent design across your healthcare application with support for both light and dark modes.

## Overview [#overview]

The Theme module integrates with React Native Paper to provide a powerful, flexible theming system that supports:

### Key Features [#key-features]

- **Material Design 3**: Built on React Native Paper's MD3 implementation
- **Custom Color System**: Extended color palettes with semantic healthcare colors
- **Responsive Spacing**: Multiplier-based spacing system for consistent layouts
- **Font loading**: Loads DM Sans variants before rendering children; Paper typography is not automatically rewired
- **Dark Mode Support**: Uses the `dark` value supplied by the app; custom colors are
  used as supplied and are not contrast-adjusted automatically
- **Healthcare Colors**: Semantic colors for success, error, and warning states
- **TypeScript Support**: Full type safety throughout the theming system
- **Performance Optimized**: Memoized theme generation

## Architecture [#architecture]

The theming system consists of several key components:

### Core Components [#core-components]

- **[ThemeProvider](/native-sdk/guide/components/theme/theme-provider/)** - Root provider component for theming context
- **[useAppTheme](/native-sdk/guide/components/theme/use-app-theme/)** - Hook for accessing theme values in components

### Utilities & Configuration [#utilities--configuration]

- **[Colors](/native-sdk/guide/components/theme/colors/)** - Comprehensive color system and palettes
- **[Multipliers](/native-sdk/guide/components/theme/multipliers/)** - Spacing and border radius configuration

## Theme Configuration [#theme-configuration]

### Basic Theme Setup [#basic-theme-setup]

```tsx
import {
  DEFAULT_COLORS,
  DEFAULT_MULTIPLIERS,
  ThemeProvider,
} from "@ovok/native";
import { Text } from "react-native-paper";

const themeConfig = {
  colors: {
    ...DEFAULT_COLORS,
    // Override specific colors
    primary: "#2563EB",
    secondary: "#7C3AED",
  },
  dark: false,
  spacingMultiplier: DEFAULT_MULTIPLIERS.spacing,
  borderRadiusMultiplier: DEFAULT_MULTIPLIERS.borderRadius,
};

const App = () => (
  <ThemeProvider theme={themeConfig}>
    <Text>Themed Text</Text>
  </ThemeProvider>
);

export default App;
```

## Color System [#color-system]

The theme provides an extensive color system with semantic meaning:

### Primary Colors [#primary-colors]

- **Primary**: Main brand color for actions and highlights
- **Secondary**: Supporting brand color for accents
- **Tertiary**: Additional brand color for variety

### Semantic Colors [#semantic-colors]

- **Success**: `#15B05D` - Positive health indicators, completed actions
- **Error**: `#ED3D31` - Critical alerts, dangerous values, errors
- **Warning**: `#FBEE37` - Attention needed, caution states

### Extended Palettes [#extended-palettes]

Blue, purple, pink, cyan, green, red, orange, and yellow each include 12 shades
(25, 50, and 100-1000). Gray includes those 12 plus the optional 1100 shade:

- **Gray**: Neutral colors for text and backgrounds
- **Blue**: Primary brand variations
- **Green**: Success and health indicators
- **Red**: Error and danger states
- **Orange**: Warning and attention colors
- **Purple, Pink, Cyan, Yellow**: Additional accent colors

## Spacing System [#spacing-system]

The theme uses a multiplier-based spacing system for consistency:

```tsx
const theme = useAppTheme();

// Usage patterns
<View
  style={{
    padding: theme.spacing(4),        // 16px (4 * 4)
    marginBottom: theme.spacing(3),   // 12px (3 * 4)
    gap: theme.spacing(2),           // 8px (2 * 4)
  }}
>
```

### Common Spacing Values [#common-spacing-values]

- `theme.spacing(1)` - 4px - Tight spacing
- `theme.spacing(2)` - 8px - Small gaps
- `theme.spacing(3)` - 12px - Medium spacing
- `theme.spacing(4)` - 16px - Standard padding
- `theme.spacing(6)` - 24px - Large spacing
- `theme.spacing(8)` - 32px - Section spacing

## Border Radius System [#border-radius-system]

Consistent border radius for visual hierarchy:

```tsx
<View
  style={{
    borderRadius: theme.borderRadius(2), // 8px - Standard cards
  }}
>
```

## Typography Integration [#typography-integration]

`ThemeProvider` requires the `@expo-google-fonts/dm-sans` peer dependency and
loads the DM Sans font assets before rendering children. Install it with
`npx expo install @expo-google-fonts/dm-sans`. Loading the assets does not
replace React Native Paper's typography configuration; set a `fontFamily`
yourself when a Paper text variant should use one of these faces.

### Available Font Weights [#available-font-weights]

- **DMSans_400Regular** - Body text, descriptions
- **DMSans_400Regular_Italic** - Emphasized body text
- **DMSans_500Medium** - Subheadings, labels
- **DMSans_500Medium_Italic** - Emphasized labels
- **DMSans_700Bold** - Headings, titles
- **DMSans_700Bold_Italic** - Emphasized headings

### Usage with React Native Paper [#usage-with-react-native-paper]

```tsx
import { Text } from "react-native-paper";

<Text variant="titleLarge">Heading Text</Text>
<Text variant="bodyMedium">Body content</Text>
<Text variant="labelSmall">Small labels</Text>
```

## Dark Mode Support [#dark-mode-support]

The app selects light or dark mode by passing `dark`:

```tsx
const themeConfig = {
  colors: DEFAULT_COLORS,
  dark: true, // Enable dark mode
  spacingMultiplier: 4,
  borderRadiusMultiplier: 4,
};
```

Dark mode automatically:

- Switches base MD3 theme to dark variant
- Uses dark MD3 base tokens for values the app does not override; test custom colors
  for contrast in both light and dark mode
- Preserves semantic color meanings
- Keeps custom color overrides