
Theming
- 111 installs
- 130 repo stars
- Updated July 12, 2026
- code-with-beto/skills
Installs a unified Expo Router color theme system with semantic tokens, native iOS and Android Material You colors, dark mode, and a useColors hook.
About
Scaffolds a unified cross-platform color theme system into an Expo Router app with semantic system tokens that resolve to native iOS labels and Android Material You colors and re-render on theme change. A developer uses it to set up dark mode, dynamic colors, and a single useColors()/useTheme() hook instead of scattering platform-specific color code.
- Installs config.ts, colors.ts, and ThemeContext.tsx with useColors() / useTheme() / useBrand() hooks
- Resolves semantic tokens to native iOS colors and Android Material You, flipping with dark/light automatically
Theming by the numbers
- 111 all-time installs (skills.sh)
- Ranked #1,033 of 2,245 Frontend Development skills by installs in the Skillselion catalog
- Data as of Jul 31, 2026 (Skillselion catalog sync)
npx skills add https://github.com/code-with-beto/skills --skill themingAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 111 |
|---|---|
| repo stars | ★ 130 |
| Last updated | July 12, 2026 |
| Repository | code-with-beto/skills ↗ |
What it does
Installs a unified Expo Router color theme system with semantic tokens, native iOS and Android Material You colors, dark mode, and a useColors hook.
Files
Expo Unified Theming
Set up one color system that works on iOS and Android at once. Instead of sprinkling Color.ios.* and Color.android.dynamic.* (or hardcoded hex) all over the app, the user gets semantic tokens (background, text, link, ...) that resolve to the right native color per platform, flip with dark/light automatically, and are read through a single useColors() hook.
This is the pattern from the Platano template, packaged so it drops into any Expo Router app.
What gets installed
Three files (bundled in assets/, adapt them to the project):
config.ts— the single source of truth. Semantic system tokens set to
"native" or a hex, plus brand colors. This is the only file the user edits day to day.
colors.ts— resolves tokens to real colors per platform, exposes
getSystemColor, useSystemColors, the brand helpers, and getNavigationTheme.
ThemeContext.tsx—ColorsProvider+ theuseColors()/useTheme()/
useBrand() hooks built on React's use.
Plus a small edit to the root _layout.tsx to wire the providers.
The two ideas that make this work
Explain these to the user, because they are the whole point and the two things people get wrong:
1. Re-render on theme change. Native and Material You colors are platform color objects, not strings React can diff. The signal that the theme changed is useColorScheme(). So the resolvers take the color scheme as an argument even when they do not read it: that makes dark/light an explicit dependency, and the value recomputes when the user toggles. The ColorsProvider reads useColorScheme() once near the root, so a toggle re-renders every consumer.
2. Two ThemeProviders, different jobs. ColorsProvider (this skill) feeds useColors() to your components. The navigation ThemeProvider themes the navigation chrome (headers, tab bars, default background). Both live at the root. Wire navigation's with getNavigationTheme(dark) so the chrome matches your tokens. Do not confuse them or drop one. On Expo SDK 56+ the navigation theme bits (ThemeProvider, DarkTheme, DefaultTheme, Theme) import from expo-router/react-navigation; on older SDKs they come from @react-navigation/native instead (see Step 1).
Step 1: Confirm the project, SDK, and the native Color API
This skill targets Expo Router apps on Expo SDK 56 or newer. SDK 56 is where the Color API (iOS system colors + Android Material You) and the expo-router/react-navigation re-exports the templates use both ship. Check the SDK and the Color API before relying on "native" tokens.
# Find the project's app dir and root layout (root-level or under src/)
ls app/_layout.tsx src/app/_layout.tsx 2>/dev/null
# Check the installed Expo SDK major version
node -e "console.log('expo', require('expo/package.json').version)" 2>/dev/null
# Confirm expo-router exports the Color API
node -e "console.log('Color export:', !!require('expo-router').Color)" 2>/dev/null
grep -rl "android.dynamic\|ios.systemBackground" node_modules/expo-router/build 2>/dev/null | head -1Branch on what you find:
- SDK 56+ (target): use the templates as written. Navigation theme bits
import from expo-router/react-navigation.
- Older than SDK 56: two adjustments are needed.
1. Import ThemeProvider, DarkTheme, DefaultTheme, and type Theme from @react-navigation/native instead of expo-router/react-navigation — in both colors.ts and _layout.tsx. (Older Expo Router did not re-export them, so you go to React Navigation directly.) 2. The Color API likely is not present. Either recommend upgrading to SDK 56, or use the hex fallback: keep the files but set the system tokens in config.ts to hex values instead of "native" (no Material You, but everything else works). getBrandColors still works; isAndroidDynamic resolves to false without Color.
Also detect the project's import alias from tsconfig.json (commonly @/* → src/* or the project root). Match that alias when you write imports. If there is no alias, use relative paths.
Step 2: Decide where the files live
Put the three files together in one folder so their relative imports (./config, ./colors) just work. Mirror the project's layout:
- App under
src/app/→ createsrc/theme/. - App at the root
app/→ createtheme/at the root.
Check for an existing theme/colors module or a ThemeProvider first. If the app already has theming, do not clobber it. Read what is there, explain the overlap to the user, and either merge into their setup or place these files under a clearly named folder and let them migrate. Never blindly overwrite.
Step 3: Create the files
Copy the three bundled templates into the chosen folder, adapting:
- import aliases / relative paths to match the project,
- the
systemtokens andbrandcolors inconfig.tsto the user's brand (ask
for their brand primary/accent, or keep the sensible defaults and tell them where to change them).
Read each asset and write it into the project (do not just symlink — these are the user's files now):
assets/config.ts→<theme>/config.tsassets/colors.ts→<theme>/colors.tsassets/ThemeContext.tsx→<theme>/ThemeContext.tsx
Keep the comments. They explain the re-render trick and the brand/dynamic behavior, which is exactly what a learner needs in their own codebase.
Step 4: Wire the root layout
Edit the existing _layout.tsx surgically — keep every provider, screen, and option already there. The target shape wraps the tree in ColorsProvider and themes navigation from an inner component that reads the color scheme:
// SDK 56+: from "expo-router/react-navigation". Older SDKs: "@react-navigation/native".
import { ThemeProvider } from "expo-router/react-navigation";
import { Stack } from "expo-router";
import { StatusBar } from "expo-status-bar";
import { useColorScheme } from "react-native";
import { getBrandColors, getNavigationTheme } from "@/theme/colors";
import { ColorsProvider } from "@/theme/ThemeContext";
export default function RootLayout() {
return (
<ColorsProvider>
{/* keep any existing providers (QueryClient, RevenueCat, gestures...) here */}
<RootLayoutInner />
</ColorsProvider>
);
}
function RootLayoutInner() {
const dark = useColorScheme() === "dark";
const { primary } = getBrandColors(dark);
return (
<>
<ThemeProvider value={getNavigationTheme(dark, primary)}>
{/* keep the project's existing <Stack> / screens exactly as they were */}
<Stack />
</ThemeProvider>
<StatusBar style={dark ? "light" : "dark"} />
</>
);
}Integration rules:
ColorsProvidermust sit above anything that callsuseColors(). Putting
it at or near the top of RootLayout is safest.
- If the file is already split into
RootLayout+ an inner component, add the
ThemeProvider and useColorScheme() there instead of creating a new inner component.
- If
expo-status-baris not installed and the project does not already manage
the status bar, you can skip the StatusBar line.
Step 5: Verify
- Typecheck if available:
npx tsc --noEmit(expect no new errors from the
three files; the most common issue is a wrong import alias).
- Tell the user to run the app, then toggle the OS appearance (or the simulator
dark/light) and confirm colors and the navigation chrome update live. On a physical Android device, changing the wallpaper should shift the Material You palette.
Step 6: Show how to use it
Give the user a short usage snippet (and offer to drop a themed example into one screen if they want to see it immediately):
import { View, Text } from "react-native";
import { useColors, useBrand } from "@/theme/ThemeContext";
export function Example() {
const { background, text, secondaryText, separator } = useColors();
const { primary } = useBrand();
return (
<View style={{ flex: 1, backgroundColor: background, padding: 16 }}>
<Text style={{ color: text, fontSize: 20, fontWeight: "600" }}>
Unified theming
</Text>
<Text style={{ color: secondaryText }}>
Same tokens on iOS and Android.
</Text>
<View style={{ height: 1, backgroundColor: separator, marginVertical: 12 }} />
<Text style={{ color: primary }}>Brand accent</Text>
</View>
);
}Outside React (a toast, a one-off style), use the non-hook accessor:
import { getSystemColor } from "@/theme/colors";
const card = getSystemColor("secondaryBackground") as string;Customizing
- Change a color everywhere: edit
config.ts. Set a token to a hex to pin
it, or back to "native" to follow the OS.
- Turn off Material You for brand on Android: set
brand.useAndroidDynamic: false and the hex brand applies on all platforms.
- Add a token: add it to
systeminconfig.ts, then add its iOS / Android
/ default entries in getNativeDefault and a line in resolveSystemColors inside colors.ts. TypeScript will point out anything you miss.
Notes
- This installs colors and brand only. It deliberately does not add spacing or
radius presets or persistence; keep it focused unless the user asks.
- The files become the user's code. Encourage them to read the comments and tweak
rather than treat it as a black box. That is the teaching goal of the lesson this skill ships with.
// Resolves the semantic tokens from config.ts into real colors, per platform,
// and keeps them reactive to dark/light changes.
//
// The whole point of this file is to UNIFY one set of names (background, text,
// link, ...) across iOS and Android so the rest of your app never reaches for
// `Color.ios.*` or `Color.android.dynamic.*` directly.
import { Color } from "expo-router";
// Expo SDK 56+. On older SDKs, import these from "@react-navigation/native".
import {
DarkTheme,
DefaultTheme,
type Theme,
} from "expo-router/react-navigation";
import { type ColorValue, Platform, useColorScheme } from "react-native";
import { type BrandColor, themeConfig } from "./config";
type SystemColorKey = keyof typeof themeConfig.system;
export type SystemColors = { [K in SystemColorKey]: string };
// The native palette per platform. iOS uses system labels/backgrounds; Android
// uses Material You dynamic tokens (they recolor with the user's wallpaper).
// `default` is the web/fallback palette for anything that isn't iOS or Android.
function getNativeDefault(key: SystemColorKey): ColorValue {
const defaults: Record<SystemColorKey, ColorValue> = Platform.select({
ios: {
background: Color.ios.systemBackground,
secondaryBackground: Color.ios.secondarySystemBackground,
text: Color.ios.label,
secondaryText: Color.ios.secondaryLabel,
separator: Color.ios.separator,
link: Color.ios.link,
},
android: {
background: Color.android.dynamic.surfaceContainerHighest,
secondaryBackground: Color.android.dynamic.surfaceContainer,
text: Color.android.dynamic.onSurface,
secondaryText: Color.android.dynamic.onSurfaceVariant,
separator: Color.android.dynamic.outlineVariant,
link: Color.android.dynamic.primary,
},
default: {
background: "#FFFFFF",
secondaryBackground: "#F2F2F7",
text: "#000000",
secondaryText: "#666666",
separator: "#E0E0E0",
link: "#007AFF",
},
})!;
return defaults[key];
}
// Non-hook accessor. Use this outside React (toasts, navigation theme, etc.).
export function getSystemColor(key: SystemColorKey): ColorValue {
const value = themeConfig.system[key];
return value === "native" ? getNativeDefault(key) : value;
}
// We accept colorScheme even though we don't read it: passing it makes the
// dark/light value an explicit dependency, so the React Compiler (and plain
// React) recompute these colors when the user flips the theme. Without this,
// a memoized result would hand back stale colors after a toggle.
function resolveSystemColors(
_colorScheme: string | null | undefined,
): SystemColors {
return {
background: getSystemColor("background") as string,
secondaryBackground: getSystemColor("secondaryBackground") as string,
text: getSystemColor("text") as string,
secondaryText: getSystemColor("secondaryText") as string,
separator: getSystemColor("separator") as string,
link: getSystemColor("link") as string,
};
}
// All system colors, reactive to dark/light. Safe with the React Compiler —
// just call it and destructure what you need.
export function useSystemColors(): SystemColors {
const colorScheme = useColorScheme();
return resolveSystemColors(colorScheme);
}
// ---------------------------------------------------------------------------
// Brand colors — your accent/primary. On Android, Material You dynamic colors
// can replace your hex brand when `brand.useAndroidDynamic` is true (default).
// ---------------------------------------------------------------------------
export const isAndroidDynamic =
Platform.OS === "android" && themeConfig.brand.useAndroidDynamic !== false;
export type ResolvedBrand = {
primary: string;
onPrimary: string;
accent: string;
onAccent: string;
};
function getAndroidDynamicBrand(
_colorScheme: string | null | undefined,
): ResolvedBrand {
return {
primary: Color.android.dynamic.primary as unknown as string,
onPrimary: Color.android.dynamic.onPrimary as unknown as string,
accent: Color.android.dynamic.secondary as unknown as string,
onAccent: Color.android.dynamic.onSecondary as unknown as string,
};
}
export function resolveBrandColor(value: BrandColor, dark: boolean): string {
return typeof value === "string" ? value : dark ? value.dark : value.light;
}
export function getBrandColors(dark: boolean): ResolvedBrand {
if (isAndroidDynamic) return getAndroidDynamicBrand(dark ? "dark" : "light");
const b = themeConfig.brand;
return {
primary: resolveBrandColor(b.primary, dark),
onPrimary: resolveBrandColor(b.onPrimary, dark),
accent: resolveBrandColor(b.accent, dark),
onAccent: resolveBrandColor(b.onAccent, dark),
};
}
export function useBrandColors(): ResolvedBrand {
const colorScheme = useColorScheme();
if (isAndroidDynamic) return getAndroidDynamicBrand(colorScheme);
return getBrandColors(colorScheme === "dark");
}
// Feeds the unified colors into React Navigation so headers, tab bars, and the
// default screen background match the rest of the app.
export function getNavigationTheme(
dark: boolean,
primaryOverride?: string,
): Theme {
const base = dark ? DarkTheme : DefaultTheme;
const primary = primaryOverride ?? getBrandColors(dark).primary;
return {
...base,
colors: {
...base.colors,
primary,
background: getSystemColor("background") as string,
card: getSystemColor("secondaryBackground") as string,
text: getSystemColor("text") as string,
border: getSystemColor("separator") as string,
notification: primary,
},
};
}
// Central theme configuration — the single source of truth for your colors.
//
// `system` tokens are semantic (what a color is FOR, not what it looks like).
// Each one is either:
// "native" -> resolved from the OS: iOS system labels/backgrounds and
// Android Material You dynamic colors (see colors.ts).
// "#RRGGBB" -> a fixed hex value you control on every platform.
//
// Start with "native" everywhere: you get correct light/dark + Material You for
// free, and you only override the tokens you actually want to brand.
export type HexColor = `#${string}`;
// A brand color is either one hex (same in light and dark) or a per-mode pair.
export type BrandColor = HexColor | { light: HexColor; dark: HexColor };
type SystemColorKey =
| "background"
| "secondaryBackground"
| "text"
| "secondaryText"
| "separator"
| "link";
type ThemeConfig = {
system: Record<SystemColorKey, "native" | HexColor>;
brand: {
primary: BrandColor;
onPrimary: BrandColor;
accent: BrandColor;
onAccent: BrandColor;
/**
* On Android, resolve brand tokens from Material You dynamic colors instead
* of the hex values above. Set to false to always use your hex brand.
*/
useAndroidDynamic: boolean;
};
};
export const themeConfig: ThemeConfig = {
system: {
background: "native",
secondaryBackground: "native",
text: "native",
secondaryText: "native",
separator: "native",
link: "native",
},
brand: {
primary: { light: "#0A7EA4", dark: "#4FC3F7" },
onPrimary: "#FFFFFF",
accent: { light: "#0A7EA4", dark: "#4FC3F7" },
onAccent: "#FFFFFF",
useAndroidDynamic: true,
},
};
// A context + hook so any component can read the resolved theme without each
// one calling useColorScheme() and the resolvers itself.
//
// The provider sits near the root. It reads useColorScheme() once, so when the
// OS theme flips, the provider re-renders and every consumer of useColors() /
// useTheme() gets fresh values automatically.
import { createContext, type ReactNode, use } from "react";
import { useColorScheme } from "react-native";
import {
getBrandColors,
type ResolvedBrand,
type SystemColors,
useSystemColors,
} from "./colors";
type ThemeValue = {
colors: SystemColors;
brand: ResolvedBrand;
dark: boolean;
};
const ThemeContext = createContext<ThemeValue | null>(null);
export function ColorsProvider({ children }: { children: ReactNode }) {
const colorScheme = useColorScheme();
const dark = colorScheme === "dark";
const colors = useSystemColors(); // reactive to dark/light
const brand = getBrandColors(dark);
return (
<ThemeContext.Provider value={{ colors, brand, dark }}>
{children}
</ThemeContext.Provider>
);
}
// Full theme: colors + brand + the dark flag.
export function useTheme(): ThemeValue {
const value = use(ThemeContext);
if (!value) {
throw new Error("useTheme must be used within a <ColorsProvider>");
}
return value;
}
// Convenience for the common case. Destructure what you need:
// const { background, text } = useColors();
export function useColors(): SystemColors {
return useTheme().colors;
}
// Convenience for brand/accent:
// const { primary, onPrimary } = useBrand();
export function useBrand(): ResolvedBrand {
return useTheme().brand;
}