Theming

Override the defaultCopy Anchor Link

TerraUI ships one theme, Electric, as defaultLight and defaultDark. To match your brand, start from it and change a few tokens with createTheme:

import { createTheme, defaultDark, defaultLight } from "@terratcg/ui";

export const brandLight = createTheme(defaultLight, {
  colors: { accent: "#7A2BD9", accentEdge: "#4E1A8C", accentSoft: "#EFE3FC", onAccentSoft: "#5A1FA3" },
  shape: { radiusMd: 22 },
});

export const brandDark = createTheme(defaultDark, {
  colors: { accent: "#B58CFF", accentEdge: "#7A4FCC", accentSoft: "#2A1D45", onAccentSoft: "#CDB2FF", onAccent: "#1A0B33" },
  shape: { radiusMd: 22 },
});

createTheme(base, overrides) deep-merges your overrides over base and returns a complete Theme. Every token you leave out keeps the base value. Neither input is changed.

It derives nothing: a new accent does not compute its accentEdge, its soft fill or the text on it. Change a colour together with the tokens that sit beside it (its edge, its soft fill, the text on it), then check the pairs under Contrast pairs.

A Theme is a plain object, so a complete hand-written theme works too. Type it as Theme and TypeScript lists every token you still owe. That path is for when you control every value, depth included.

Light and darkCopy Anchor Link

Your app picks the appearance and owns any stored preference. Give ThemeProvider one theme at a time:

import { ThemeProvider } from "@terratcg/ui";
import { useColorScheme } from "react-native";

import { brandDark, brandLight } from "./theme";

export function Root({ children }: { children: React.ReactNode }) {
  const dark = useColorScheme() === "dark";
  return <ThemeProvider theme={dark ? brandDark : brandLight}>{children}</ThemeProvider>;
}

Build the light and dark themes from defaultLight and defaultDark respectively: each carries its own depth, tuned for its ground. See ThemeProvider and feedback.

A custom themeCopy Anchor Link

Tide is a sample theme made with createTheme: coral actions on sand and deep navy, rounder corners, longer travel and heavier labels. The same components take on a different identity. Tide is not exported; copy what you need.

TideCopy Anchor Link

The same Card, Switch, Progress and Buttons in Tide, a custom theme: coral keys on sand, rounder and deeper.

iOSAndroidTry it (web)

iPhone 17 Pro · iOS 27

Copy Text

import {
  Button,
  ButtonText,
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
  Progress,
  RowContent,
  RowTitle,
  SwitchRow,
  ThemeProvider,
  useTheme,
} from "@terratcg/ui";
import { useState } from "react";
import { View } from "react-native";

import { tideDark, tideLight } from "../../themes/tide";

export default function TideTheme() {
  // Follow the surrounding appearance; an app would read useColorScheme().
  const tide = useTheme().scheme === "dark" ? tideDark : tideLight;
  const [reminders, setReminders] = useState(true);
  return (
    <ThemeProvider theme={tide}>
      <View style={{ backgroundColor: tide.colors.background, borderRadius: 28, padding: 20, width: 340, maxWidth: "100%" }}>
        <Card>
          <CardHeader>
            <CardTitle>Morning swim</CardTitle>
            <CardDescription>Three lengths left before the pool closes.</CardDescription>
          </CardHeader>
          <CardContent style={{ gap: 16 }}>
            <Progress value={0.7} accessibilityLabel="Swim progress" />
            <SwitchRow value={reminders} onValueChange={setReminders} accessibilityLabel="Reminders">
              <RowContent>
                <RowTitle>Reminders</RowTitle>
              </RowContent>
            </SwitchRow>
          </CardContent>
          <CardFooter style={{ gap: 12 }}>
            <Button variant="secondary">
              <ButtonText>Later</ButtonText>
            </Button>
            <Button>
              <ButtonText>Start</ButtonText>
            </Button>
          </CardFooter>
        </Card>
      </View>
    </ThemeProvider>
  );
}

Safe to changeCopy Anchor Link

Colours, typography, spacing, shape and motion change how TerraUI looks without changing how its material works. Every value below is Electric's.

name and scheme identify the theme: a family name of your choosing, and "light" or "dark".

ColoursCopy Anchor Link

Every control reads its colours from these semantic tokens, never from literals.

TypographyCopy Anchor Link

Light and dark share these values.

Sizes are in points and scale with the system text size.

SpacingCopy Anchor Link

ShapeCopy Anchor Link

MotionCopy Anchor Link

Advanced: depthCopy Anchor Link

depth is the tactile material itself: how far a key travels, the shadows that seat it on the shell, the light along its rims and the recess of a well. The Material page explains each treatment. Change these tokens to tune the material for your palette, for example to tint the shadows with your ink, and check every control in both appearances afterwards.

Shadows are written as their vertical offset, blur and colour, in points. Every shadow is a React Native boxShadow, so the material looks the same on iOS and Android.

Contrast pairsCopy Anchor Link

Text and icons sit on these pairs. Each must reach 4.5:1 to pass WCAG AA for body text. Check them whenever you change a colour. These are Electric's ratios, rounded down:

danger on dangerSoft is what a danger InlineNotice draws, so a theme that changes either colour should check that pair first: it has the least room.