Theming, studio branding and dark mode

Two independent systems color the app.

The theme decides neutral colors: backgrounds, text, hairlines, status colors. It has a dark and a light palette.
The brand decides the accent color and identity: the studio’s primary color, logo and name. It comes from the server per studio.

A screen reads both: useColors() for neutrals and useBrandPalette() for the accent.

Tokens

src/theme/index.ts re-exports everything.

Spacing, radius, sizes

From src/theme/spacing.ts:

Token	Values
`spacing`	`xs` 4, `sm` 8, `md` 12, `lg` 16, `xl` 20, `xxl` 24, `xxxl` 32, `huge` 40, `screen` 16
`radius`	`sm` 10, `md` 14, `lg` 18, `xl` 20, `xxl` 28, `pill` 999
`sizes`	`control` 56, `controlCompact` 48, `ring` 88, `ringStroke` 9, `maxContentWidth` 480

spacing.screen is the horizontal page gutter. sizes.maxContentWidth caps the content column, which keeps the layout sane in the web preview and on wide devices.

Typography

src/theme/typography.ts defines twelve variants. AppText takes one through its variant prop.

Variant	Size / line height	Weight
`display`	34 / 40	extrabold
`headline`	28 / 34	bold
`titleLg`	20 / 26	bold
`titleMd`	17 / 23	semibold
`body`	17 / 26	regular
`bodySm`	15 / 22	regular
`label`	16 / 20	semibold
`labelSm`	14 / 18	semibold
`caption`	13 / 18	regular
`badge`	12 / 16	semibold
`numeric`	24 / 28	extrabold
`kicker`	12 / 16, letter spacing 1.6	bold

variantColorKey maps each variant to ink, inkSecondary or inkTertiary. AppText resolves that key against the active palette, so text recolors with the theme. The colors baked into the typography objects are a static fallback only.

Fonts

fontFamily is resolved once at module load from the stored language:

Language	Body family	Tab label family
Arabic	IBM Plex Sans Arabic	IBM Plex Sans Arabic
Hebrew	Inter	IBM Plex Sans Hebrew
Others	Inter	Inter

The root layout also loads Heebo and Assistant for the story share cards, Rubik for the glass home skin, Karantina and Assistant for the poster skin, and Varela Round for the bento skin. Because the family is picked at module load, a language change needs the reload that setLanguage performs.

Palettes

src/theme/colors.ts exports darkColors and lightColors with identical keys, typed as ThemePalette.

Group	Keys
Surfaces	`background`, `backgroundElevated`, `surface`, `surfaceMuted`, `surfacePressed`
Text	`ink`, `inkSecondary`, `inkTertiary`, `inkDisabled`
Lines	`hairline`, `hairlineStrong`
Glass	`glassFill`, `glassStroke`, `glassScrim`, `glassChipTint`, `sheetSurface`, `sheetCardSurface`
Default brand	`brand`, `brandPressed`, `brandDeep`, `brandTint`, `brandTintStrong`, `onBrand`
Status	`success`, `warning`, `danger`, `info`, each with a `Tint` variant
Rings	`ringCalories`, `ringProtein`, `ringCarbs`, `ringFat`, `ringWater`, `ringSteps`, `ringTrack`
Fixed	`white`, `black`

The dark background is #0B0B14, which matches the native splash and backgroundColor in app.json. The light background is #F4F6F9. colors is a static export of the dark palette for the few non-reactive uses. Components should use the hook.

colors.brand in the palette is the Perform default red. For anything the studio should recolor, read useBrandPalette().brand instead.

Theme store

useThemeStore in src/theme/themeStore.ts holds scheme, the matching colors object and hasChoice.

Action	Effect
`hydrate()`	Loads the trainee’s own choice if there is one, else the studio default, else stays dark
`setScheme(scheme)`	Saves the trainee’s choice and marks `hasChoice`
`toggle()`	Flips dark and light through `setScheme`
`applyDefault(scheme)`	Saves the studio default. Changes the visible scheme only when the trainee has not chosen

Who wins

The trainee’s choice. Set by the Dark mode switch on the profile tab, which calls toggle().
The studio default. authStore.applyStudioScheme calls applyDefault when studio.branding.appTheme is 'dark' or 'light'.
Dark.

The two sources are stored under separate keys so one cannot overwrite the other:

Key	Meaning
`perform_theme`	The trainee’s scheme
`perform_theme_override`	`'true'` once the trainee has chosen. `themeStorage.getChoice()` returns null without it
`perform_theme_studio`	The studio’s default scheme

The app does not follow the operating system setting. userInterfaceStyle in app.json is dark. The root layout hydrates the theme before the auth store, and sets the status bar and Android navigation bar style from the scheme.

Themed styles

Static StyleSheet.create cannot react to the scheme. Use useThemedStyles with a factory declared outside the component:

const makeStyles = (colors: ThemePalette) =>
  StyleSheet.create({
    card: { backgroundColor: colors.surface, borderColor: colors.hairline },
  });

function Thing() {
  const styles = useThemedStyles(makeStyles);
}

The hook memoizes on the palette and the factory identity, so the factory must be stable. The auth screens are the exception. They always use darkColors directly and do not follow the theme.

Studio brand

src/features/branding/brandStore.ts holds a Brand and a derived BrandPalette.

export type Brand = {
  primaryColor: string;
  logoUrl: string | null;
  iconUrl: string | null;
  studioName: string | null;
  storyBackgroundUrl: string | null;
  storyShareText: string | null;
  instagramHandle: string | null;
  coachAvatarUrl: string | null;
  storyProfileImage: string | null;
  homeTheme: HomeTheme;
};

Where it comes from

authStore.brandFromStudio(studio) maps studio.branding from /v1/trainee/me and from the sign in response, then calls useBrandStore.apply(). This runs on sign in, on studio switch and on every refreshSession(). A coach who changes branding in the dashboard sees it in the app the next time the trainee opens it. Mapping rules worth knowing:

logoUrl falls back to iconUrl.
storyBackgroundUrl falls back to the older selfieExampleUrl field.
primaryColor must be a six digit hex. Anything else falls back to the default red.
homeTheme must be one of HOME_THEMES. Anything else becomes classic.

apply() persists the normalized brand under perform_brand. hydrate() restores it at launch so the login screen is already in the studio’s colors. reset() runs on sign out.

Derived palette

paletteFor(primaryColor) builds:

Key	Derivation
`brand`	The primary color
`brandPressed`	`darken(brand, 0.12)`
`brandTint`	`rgba(brand, 0.16)`
`brandTintStrong`	`rgba(brand, 0.3)`
`onBrand`	White

Color helpers

src/theme/brandColor.ts:

Function	Purpose
`isValidHex(value)`	Type guard for six digit hex
`rgba(value, alpha)`	Accepts hex or an existing `rgb()` / `rgba()` string and multiplies alpha
`darken(value, amount)`	Scales each channel towards black
`luminance(value)`	Relative luminance from 0 to 1
`ensureVibrant(value, fallback)`	Returns the fallback when luminance is under 0.28
`stepAway(color, anchor, amount)`	Pushes a color further from an anchor color

useAuthAccent() uses ensureVibrant so a very dark studio color is replaced by #FF5F4D on the always-dark login screens.

Home skins

HOME_THEMES is ['classic', 'glass', 'poster', 'bento']. The coach picks one for the studio in the dashboard branding settings, and HomeScreen switches on useHomeTheme(). The skin also dresses every other screen. Screen renders SkinBackground behind its content whenever the skin is not classic:

Skin	Backdrop
`classic`	None. The theme background plus `AmbientGlow`
`glass`	The coach’s `storyBackgroundUrl` image, or a brand gradient when there is none, under two scrim gradients
`poster`	Diagonal pinstripes and a brand glow at the top
`bento`	A flat tone

Base colors per skin and scheme are in SKIN_BASE_COLOR. The comment in SkinBackground.tsx notes that these recipes mirror the skin home screens and must change together.

Brand in the header and widgets

BrandTopBar shows the page title and the studio logo. If the logo fails to load it falls back to the studio name in the brand color. widgetBrandLogo.ts downloads the studio logo into the shared widgets directory as brand-logo.png so the iOS widgets and Live Activity can show it. With no studio logo it installs the bundled Perform mark instead.

Rules for new UI

Neutrals from useColors(). Accent from useBrandPalette(). No hard-coded hex for either.
Spacing and radius from the tokens.
Text through AppText with a variant.
Styles that depend on the palette through useThemedStyles.
The project rule is no shadows. ProgressBar has an optional glow, which is the one deliberate exception in the kit.

​Tokens

​Spacing, radius, sizes

​Typography

​Fonts

​Palettes

​Theme store

​Who wins

​Themed styles

​Studio brand

​Where it comes from

​Derived palette

​Color helpers

​Home skins

​Brand in the header and widgets

​Rules for new UI

Tokens

Spacing, radius, sizes

Typography

Fonts

Palettes

Theme store

Who wins

Themed styles

Studio brand

Where it comes from

Derived palette

Color helpers

Home skins

Brand in the header and widgets

Rules for new UI