> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobile-starter.amisi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme

> Use configured tokens, persisted color schemes, color helpers, and shadows.

# @amisi-mobile-starter/theme

`@amisi-mobile-starter/theme` builds `defaultTheme` from normalized `@amisi-mobile-starter/config` UI values and fixed font, spacing, and typography defaults.

## Theme provider

```tsx theme={null}
import { ThemeProvider } from '@amisi-mobile-starter/theme';

export const AppRoot = () => {
  return <ThemeProvider>{/* app */}</ThemeProvider>;
};
```

`ThemeProvider` accepts `children` and optional `theme?: ThemeConfig`. Its initial `colorScheme` is `system`. It loads and saves `light | dark | system` under the secure-store key `theme-color-scheme` and synchronizes native `Appearance` when you select light or dark.

## Hooks

```tsx theme={null}
import { useColorScheme, useColors, useTheme } from '@amisi-mobile-starter/theme';

export const ThemeExample = () => {
  const themeContext = useTheme();
  const colors = useColors();
  const { colorScheme, isDark, setColorScheme, toggleColorScheme } =
    useColorScheme();

  return null;
};
```

All three hooks require `ThemeProvider`.

`useTheme()` returns `theme`, `colorScheme`, `isDark`, `colors`, `setColorScheme`, and `toggleColorScheme`. `useColorScheme()` returns only `colorScheme`, `isDark`, `setColorScheme`, and `toggleColorScheme`. `useColors()` returns the resolved `ThemeColors` object directly.

Although `ThemeContextValue` types `setColorScheme` as returning `void`, the implementation is asynchronous internally and callers should not rely on a returned persistence promise.

## Theme shape

`ThemeConfig` contains:

* `colors.light` and `colors.dark`
* `fonts`: `primary`, `secondary`, `mono`, `useGoogleFonts`
* `spacing`: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`
* `borderRadius`: `sm`, `md`, `lg`, `xl`, `full`
* `shadows`: `color`, `sm`, `md`, `lg`
* `controls`: `sm`, `md`, `lg`
* `typography.fontSize`, `typography.fontWeight`, and `typography.lineHeight`

Each `ThemeColors` object has `primary`, `secondary`, `accent`, `background`, `surface`, `border`, nested `text.primary|secondary|muted`, `error`, `success`, `warning`, and `info`.

Configure colors, radii, shadows, and controls in `amisi.config.json` at `theme.ui.light`, `theme.ui.dark`, `theme.ui.radius`, `theme.ui.shadow`, and `theme.ui.controls`.

## Utility exports

```ts theme={null}
import {
  alpha,
  darken,
  getContrastColor,
  getShadowStyle,
  isDark,
  isLight,
  lighten,
} from '@amisi-mobile-starter/theme';
```

`lighten(color, amount)` and `darken(color, amount)` return hex strings. `alpha(color, opacity)` returns a hexa string. `getContrastColor(backgroundColor)` returns `#000000` for a light background or `#ffffff` otherwise.

`getShadowStyle(theme, level)` accepts `sm | md | lg` and returns a React Native `ViewStyle` using the configured shadow color and depth.