Theming

A GPUIxUI theme is plain data. Components never carry a colour literal; they read a semantic role such as colors.primary, spacing.md or radius.md from the nearest ThemeProvider. Switching the provider restyles the subtree without touching component code.

import { ThemeProvider } from "@gpuixui/tokens/react";
import { darkTheme } from "@gpuixui/tokens";

<ThemeProvider theme={darkTheme}>
  <App />
</ThemeProvider>;

Theme shapeCopy Anchor Link

Every theme has the same fields:

Colour rolesCopy Anchor Link

Roles describe intent, not a ramp shade. There are 47 of them; the families that matter most on a page are:

The full catalogue, including the four status families and their soft pairs, is in docs/tokens.md. colorRoles exports the ordered list, so a docs table or a theme editor can enumerate it instead of copying names.

Built-in themesCopy Anchor Link

Four themes ship, and getTheme selects one by mode and contrast:

import { getTheme } from "@gpuixui/tokens";

const theme = getTheme("dark"); // darkTheme
const accessible = getTheme("dark", "high"); // high-contrast dark

Override a themeCopy Anchor Link

extendTheme merges overrides into a base theme without mutating it; createTheme starts from a built-in mode.

import { createTheme } from "@gpuixui/tokens";

export const acme = createTheme({
  mode: "dark",
  name: "Acme",
  colors: { primary: "#7C5CFF", ring: "#9B8CFF" },
  radius: { md: 8 },
  density: "compact",
});

Only what changes is written. Every other role is inherited, so a brand cannot accidentally drop a role a component reads.

DensityCopy Anchor Link

Density changes control geometry, never type. compact is for toolbars and data-dense desktop surfaces; comfortable is the default.

const compact = createTheme({ mode: "dark", density: "compact" });

Platform typographyCopy Anchor Link

platformTheme keeps the colours, scales and mode, and swaps only the type families for one platform. It is the hook for the macOS/Windows/Linux looks.

import { platformTheme, themes } from "@gpuixui/tokens";

const windows = platformTheme(themes.dark, "win32");

Read the themeCopy Anchor Link

useTheme returns the nearest theme, or the light theme when no provider exists. Components use it internally; an application can use it for its own layout without duplicating a colour.

import { useTheme } from "@gpuixui/tokens/react";

const theme = useTheme();
const muted = theme.colors.mutedForeground;