Theming

Most apps only need to edit the shared tokens. Use xstyle for one-off changes. Add the theme runtime only when users need to switch between light, dark, and system modes.

How theming works

Yopem components read semantic values such as primary, background, foreground, font, and radius from src/styles/tokens.stylex.ts. Change that file once to update every component.

Change the whole app

Complete Installation first. Then open the copied token file and replace the values you want. Keep all other existing values.

export const lightValues = {
  "--primary": "#1d4ed8",
  "--primary-foreground": "#ffffff",
  "--ring": "#2563eb",
  "--font-heading": '"App Sans", system-ui, sans-serif',
  "--radius-lg": "0.75rem",
}

export const darkValues = {
  ...lightValues,
  "--primary": "#93c5fd",
  "--primary-foreground": "#172554",
  "--ring": "#60a5fa",
}

Change background and foreground pairs together so text remains readable. Font tokens select a font family but do not download its files. Run a production build after editing tokens.

Component overrides

Use xstyle when one component should look different. Yopem applies it after default styles and variants.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"

const styles = stylex.create({
  pill: { borderRadius: "999px" },
})

export function SaveButton() {
  return <Button xstyle={styles.pill}>Save changes</Button>
}

Use stylex.props for native HTML elements. Use xstyle for Yopem components. Preserve focus, hover, and disabled styles when overriding those states.

Add dark mode

Skip this section if your app has one fixed theme. A static light or dark theme needs no provider and no client script.

For user-selectable light, dark, and system modes, copy these two files:

src/theme/theme.tsx

import {
  darkTheme,
  lightTheme,
  rootStyles,
  themeMarker,

src/theme/theme-provider.tsx

"use client"

import type React from "react"

import {

Add the script before hydration and wrap your app with the provider. This example keeps TanStack Start head and script components in place. Adapt only those framework-specific imports for another SSR framework.

import "@/styles/styles.css"
import * as stylex from "@stylexjs/stylex"
import { createRootRoute, HeadContent, Scripts } from "@tanstack/react-router"
import { rootStyles } from "@/styles/tokens.stylex"
import { getRootThemeProps, ThemeScript } from "@/theme/theme"
import { ThemeProvider } from "@/theme/theme-provider"

export const Route = createRootRoute({ shellComponent: RootDocument })

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html
      {...getRootThemeProps("light")}
      data-theme="light"
      lang="en"
      suppressHydrationWarning
    >
      <head>
        <HeadContent />
        <ThemeScript />
      </head>
      <body {...stylex.props(rootStyles.body)}>
        <ThemeProvider>{children}</ThemeProvider>
        <Scripts />
      </body>
    </html>
  )
}

Add any control that calls useTheme. Use your existing Select or Segmented Control component in a real interface.

"use client"

import { useTheme } from "@/theme/theme-provider"

export function ThemePicker() {
  const { theme, setTheme } = useTheme()

  return (
    <fieldset>
      <legend>Appearance</legend>
      {(["light", "dark", "system"] as const).map((value) => (
        <label key={value}>
          <input
            type="radio"
            name="theme"
            value={value}
            checked={theme === value}
            onChange={() => setTheme(value)}
          />
          {value}
        </label>
      ))}
    </fieldset>
  )
}

ThemeScript and ThemeProvider must use matching defaults. If your Content Security Policy blocks inline scripts, pass the same per-request nonce allowed by your CSP to ThemeScript.