Styling and theming the Expo app | Expo Supabase SaaS Kit

The Expo app is styled with Tailwind utility classes, the same way apps/web is. This page covers the one file you edit to rebrand it, how the light/dark/system preference is stored and applied, what @kit/mobile-ui gives you, and where a new component belongs so a component-library resync does not delete it.

The model: Tailwind v4 without a config file

Styling goes through Uniwind, which compiles Tailwind v4 for React Native. You write className on React Native components and Uniwind resolves the utilities into RN styles at build time through its Metro transformer.

Two things differ from what you know from the web app:

Because there is no cascade, only utilities Uniwind can map to an RN style property do anything. A class that has no RN equivalent is resolved and then dropped silently, with no build warning. This is the single most common surprise when porting a web component by hand.

Installed versions, from pnpm-workspace.yaml (the expo named catalog) and the resolved lockfile:

apps/native/global.css — the whole theme

This is the Tailwind + Uniwind entrypoint. It is registered with Metro in apps/native/metro.config.js:

const config = withUniwindConfig(getDefaultConfig(__dirname), {
  cssEntryFile: './global.css',
  dtsFile: './uniwind-types.d.ts',
});

and imported exactly once, as the first line of apps/native/app/_layout.tsx:

import '../global.css';

Do not import it anywhere else, and do not remove either half of metro.config.js — the withUniwindConfig wrapper must stay outermost, and the resolver block under it pins a single copy of React so @kit/* packages cannot drag a second one into the bundle.

Scanning mobile-ui's classes

@source '../../packages/mobile-ui/src/**/*.{ts,tsx}';

Tailwind's automatic source detection is rooted at the directory containing the CSS entry file — Uniwind passes base: path.dirname(cssPath) when it compiles, which is apps/native/. Class names that appear only inside packages/mobile-ui/src are therefore invisible to the compiler, and every utility used by a Button, Card or Input would be stripped from the generated stylesheet. The @source directive adds that tree back.

If you add another workspace package that ships className strings, it needs its own @source line here.

The tokens

Uniwind's bundler recognises @variant <theme> rules, and it requires every registered theme to declare the same variable set. So the palette lives in two mirrored blocks, @variant light and @variant dark, and non-themed tokens live in the @theme block above them.

Plus one non-themed token in the @theme block: --radius: 0.5rem.

Each --color-<name> token generates the usual utility families — bg-<name>, text-<name>, border-<name> — so bg-background, text-muted-foreground and border-border behave exactly as on web.

Rebranding

Editing the palette is the whole job:

1. Open apps/native/global.css.
2. Change the values inside @variant light. Keep every declared token — Uniwind rejects a theme that declares a different variable set from its sibling.
3. Change the matching values inside @variant dark.
4. Adjust --radius in the @theme block if your brand is rounder or squarer.
5. Restart Metro. The stylesheet is generated at bundle time; a running server picks up CSS edits, but after a metro.config.js or dependency change use pnpm start:native:clear.

You do not need to touch any component to rebrand, because every component in the kit references tokens rather than literal colours.

Brand surfaces that are not CSS tokens — the app icon, the Android adaptive-icon background (#ffffff in apps/native/app.json), the splash screen — are build-time native config. See docs/native/building-shipping.mdoc and docs/native/config-requirements.mdoc.

Light, dark and system

The user-facing preference is tri-state (light | dark | system), and it is owned by React state, not by Uniwind. apps/native/lib/theme/theme-preference-context.tsx explains why: Uniwind stores only the resolved binary theme, so the 'system' intent is lost the moment the OS scheme flips.

Uniwind.setTheme('light' | 'dark') also calls RN's Appearance.setColorScheme(), so useColorScheme() agrees with the chosen theme app-wide; setTheme('system') resets Appearance to unspecified and hands control back to the OS.

Persistence uses SecureStore rather than a plain key-value store because the app already depends on it for the session (see docs/native/authentication.mdoc), and SecureStore items are app-sandboxed on both the iOS Keychain and the Android Keystore — which is also why a flat, non-namespaced key is safe here.

The isReady gate

preference is null until the SecureStore read resolves. During that window Uniwind has not been told anything, so it renders with the OS scheme — and a user who chose dark on a light-mode device would see a white flash on every cold start. apps/native/app/_layout.tsx blocks the first frame instead:

const { preference, isReady } = useThemePreference();
if (!isReady) {
  return (
    <>
      <StatusBar style="light" />
      <View style={{ flex: 1, backgroundColor: '#000' }} />
    </>
  );
}

The black frame is deliberate: it is unbranded, so it reads as part of the launch sequence in either theme, and it is a plain style (not a className) precisely because the themed token is what is not yet trustworthy. If you add work that must happen before the first painted screen, gate it in the same place rather than adding a second splash.

React Navigation chrome

Headers, card backgrounds and the screen background underneath your content are painted by React Navigation, which reads a Theme object rather than class names. useNavigationTheme bridges the two: it resolves the tokens through useThemeColors, starts from DefaultTheme/DarkTheme depending on the colour scheme, and overrides background, card, text, border, primary and notification (mapped from --color-destructive). It is applied once, in app/_layout.tsx:

<ExpoRouterThemeProvider value={navigationTheme}>
  <Stack screenOptions={{ headerShown: false }} />
</ExpoRouterThemeProvider>

Each override falls back to the base navigation theme's own value if a token fails to resolve, so a typo in a token name degrades to the stock colour instead of rendering undefined.

When you need useThemeColors

Reach for it only when an API wants a real colour value as a prop and cannot be given a class. The native tab bar is the live example — it builds its appearance from explicit props and ignores the navigation theme entirely:

const { muted, mutedForeground, foreground } = useThemeColors();
<NativeTabs
  backgroundColor={muted}
  iconColor={{ default: mutedForeground, selected: foreground }}
  labelStyle={{
    default: { color: mutedForeground },
    selected: { color: foreground },
  }}
  disableIndicator
/>

The hook is reactive (it wraps Uniwind's useCSSVariable), so colours follow a theme switch without a remount. It exposes eight tokens: background, card, foreground, muted, mutedForeground, border, primary, destructive, each typed string | undefined. If you need a ninth, add it to the TOKENS array and the destructure in the same order — the file notes that the order is index-mapped.

For everything else, use a className. Anything you can express as a utility should be one.

@kit/mobile-ui

packages/mobile-ui is the native mirror of @kit/ui. Components are React Native Reusables (RNR) — shadcn-style primitives copied into src/components/ui/ by the RNR CLI, built on @rn-primitives/* — so the API is close enough to @kit/ui that porting a web feature is mostly mechanical.

The authoritative component list is the exports map in packages/mobile-ui/package.json:

There is no barrel file and no . export. Import flat, one component per subpath:

import { Icon } from '@kit/mobile-ui/icon';
import { Separator } from '@kit/mobile-ui/separator';
import { Text } from '@kit/mobile-ui/text';
import { cn } from '@kit/mobile-ui/utils';

Never write a deep path into src/components/ui/ from outside the package — a path that is not in exports is not part of the contract and will break on the next resync.

Three standing rules when you write native UI:

1. Merge classes with cn() from @kit/mobile-ui/utils (twMerge(clsx(...))), so a caller's className can override a component's defaults.
2. Use semantic classes (bg-background, text-muted-foreground, border-border) and never a hardcoded RN colour. A literal #111827 is invisible to the theme switch and will look wrong in one of the two modes.
3. Wrap text in Text from @kit/mobile-ui/text rather than RN's Text, so text-colour class context propagates to nested Icons.

@kit/mobile-ui/form is covered in docs/native/forms.mdoc; @kit/mobile-ui/trans in docs/native/i18n.mdoc.

The rule that matters: never edit src/components/ui/

Project-specific work goes in packages/mobile-ui/src/makerkit/, a sibling directory the CLI never touches. It currently holds:

This is the same split packages/ui uses on web: packages/ui/src/shadcn/ is generated and disposable, packages/ui/src/makerkit/ is yours. Learning one convention gets you both.

If a generated component genuinely needs different behaviour, prefer wrapping it in src/makerkit/ over editing it. If you must edit the original, treat that edit as a patch you will have to re-apply, and record it — a resync will silently drop it.

Adding an RNR component

RNR ships more components than the kit vendors. To pull one in:

cd packages/mobile-ui
pnpm exec cli add <component> --styling-library uniwind

The CLI is configured by packages/mobile-ui/components.json (styling library uniwind, icon library lucide, and — importantly — tailwind.css pointing at ../../apps/native/global.css, so it reads your tokens rather than writing its own). To resync everything:

pnpx @react-native-reusables/cli@latest add --all --yes --overwrite --styling-library uniwind

Every add writes files that import each other through @/ aliases. packages/mobile-ui/tsconfig.json declares no paths for @/, so those imports do not resolve — rewrite them to relative paths before doing anything else:

cd packages/mobile-ui/src/components/ui
for f in *.tsx; do
  sed -i.bak \
    -e "s|from '@/components/ui/\([^']*\)'|from './\1'|g" \
    -e "s|from '@/lib/utils'|from '../../lib/utils'|g" \
    -e "s|from '@/lib/\([^']*\)'|from '../../lib/\1'|g" \
    -e "s|from '@/hooks/\([^']*\)'|from '../../hooks/\1'|g" \
    "$f"
  rm "$f.bak"
done

Then add the new component to the exports field of packages/mobile-ui/package.json — until you do, @kit/mobile-ui/<name> is not importable — and run pnpm typecheck.

One packaging note: RNR installs its @rn-primitives/* dependencies with pnpm add under the hood, and this workspace's catalogMode: prefer rewrites those into catalog: entries in pnpm-workspace.yaml automatically. Check that diff rather than reverting it.

Adding your own component

Two homes, one question:

The dividing line is dependencies, not reusability. Anything that imports ~/features/*, ~/lib/* or the app's i18n cannot live in the package. Layout glue that composes domain features (the home header, the tab stack) goes higher still, in apps/native/components/. The full layer model and the one-way import rule are in docs/native/project-structure.mdoc.

Before you build a shared widget, check what already exists in apps/native/features/makerkit/components/:

Icons

Icons come from lucide-react-native, rendered through the Icon wrapper from @kit/mobile-ui/icon. You pass the Lucide component as as and style it with classes — this is how app/(home)/theme.tsx does it:

import { Check, Sun, type LucideIcon } from 'lucide-react-native';
import { Icon } from '@kit/mobile-ui/icon';
<Icon as={Sun} className="text-foreground size-5" />
<Icon as={Check} className="text-primary size-5" />

Icon defaults to text-foreground size-5 and inherits the surrounding text colour context, so an icon inside a muted row picks up the muted colour without being told.

For icons that are decoration rather than information, set accessibilityElementsHidden / importantForAccessibility="no-hide-descendants" on the wrapper, as AppLogo does.

Two type-level gotchas

placeholderClassName. Both apps/native/uniwind-env.d.ts and packages/mobile-ui/src/uniwind-env.d.ts augment RN's TextInputProps with an optional placeholderClassName, a leftover from an RNR-vs-Uniwind prop mismatch. Nothing in the repo passes it today — the vendored input.tsx and textarea.tsx colour their placeholders with Uniwind's own placeholderTextColorClassName, which resolves through accentColor and therefore needs an accent-* utility (accent-muted-foreground), not a text-* one. A text-* class there yields undefined.

export {} is load-bearing. Both uniwind-env.d.ts files declare export {}. Without it the file is a global script rather than a module, and the declare module 'react-native' block inside would replace the react-native module declaration instead of augmenting it — breaking every import { Platform } from 'react-native' in the app. If you touch those files, keep the export {}.

Neither file needs manual maintenance otherwise. uniwind-types.d.ts next to them is generated by Metro on first run, is gitignored, and is referenced from apps/native/tsconfig.json.