Theme
The @puzzle-ui/theme package owns Puzzle's design tokens, color themes, typography, fonts, and theme scoping.
@puzzle-ui/theme is the source of truth for Puzzle's visual design.
It turns a typed token object into CSS custom properties, loads configured
fonts, resolves light and dark color schemes, and lets you scope a theme to the
whole document or a single subtree.
All @puzzle-ui/ui components consume these CSS custom properties, so a single Theme provider styles your application.
Install
npm install @puzzle-ui/themeimport { Theme } from "@puzzle-ui/theme";Quick start
Wrap your application in a single Theme at the root. Without any props it applies the default tokens, follows the user's system color scheme, and injects Puzzle's global styles.
import { Theme } from "@puzzle-ui/theme";
const App = () => (
<Theme>
<YourApp />
</Theme>
);A customized root theme can combine a color theme, fonts, and token overrides.
<Theme
theme="system"
colorTheme="cobalt-sky"
fonts={{
heading: { family: "Sora" },
body: { family: "Inter" },
}}
tokens={{
radius: { md: "0.5rem" },
}}
>
<YourApp />
</Theme>What the package provides
| Area | Description | Documentation |
|---|---|---|
| Theme provider | Injects token CSS variables, loads fonts, and applies global styles at root or local scope. | Theme Provider |
| Design tokens | Typed token groups for spacing, radius, shadows, elevation, borders, layout, motion, and z-index. | Design Tokens |
| Colors | Semantic color roles, light/dark color schemes, and built-in color themes. | Colors |
| Typography and fonts | Named typography roles, fluid font sizes, and Google Font loading. | Typography and Fonts |
| Breakpoints | Shared responsive breakpoints for JavaScript and CSS. | Breakpoints |
| Component overrides | Global link and image component overrides for router and framework integration. | Component Overrides |
Exports
import {
Theme,
GoogleFont,
createGoogleFontUrl,
BREAKPOINTS,
} from "@puzzle-ui/theme";
import type {
ThemeProps,
ThemeScope,
ThemeMode,
ThemeTokens,
ThemeTokenOverrides,
ThemeColorSchemeTokens,
ThemeTypographyRoleTokens,
ThemeTypographyFontRole,
TypographyStyle,
ColorTheme,
Breakpoint,
FontRole,
FontStyle,
FontDisplay,
FontConfig,
ResolvedFontConfig,
FontStylesheet,
ThemeFonts,
ThemeComponents,
ThemeLinkComponent,
ThemeLinkComponentConfig,
ThemeImageComponent,
} from "@puzzle-ui/theme";How it works
Theme resolves the default tokens, the optional color theme, and
your token overrides into a flat map of CSS custom properties.
It renders a style element that assigns those variables to the document root or to a generated scope attribute. Static CSS shipped with the package maps scheme-specific variables onto semantic variables based on the active mode, including automatic prefers-color-scheme handling in system mode.
Token values are validated before they are written into CSS. Unknown token names and invalid values should be corrected rather than silently ignored.