Configure a Panda theme
Define the tokens, semantic tokens, conditions, breakpoints, and global rules that every component in a Brix application or UI library shares.
This guide covers full-stack Preact applications and UI libraries. Browser-only React applications do not use managed Panda; see the React application boundary.
Create the configuration
#Add a root panda.config.ts that default-exports definePandaConfig from brix/panda:
import { definePandaConfig } from "brix/panda";
export default definePandaConfig({
theme: {
extend: {
tokens: {
colors: {
brand: { value: "#0057b8" },
canvas: { value: "#ffffff" },
ink: { value: "#172033" },
},
},
semanticTokens: {
colors: {
surface: { value: { base: "{colors.canvas}", _dark: "{colors.ink}" } },
text: { value: { base: "{colors.ink}", _dark: "{colors.canvas}" } },
},
},
},
},
globalCss: {
"html, body": { margin: "0", backgroundColor: "surface", color: "text" },
},
});
The file is optional. Without it, Brix generates utilities from the same defaults with no project
tokens. Only the .ts name is loaded: a panda.config.mjs, .mts, .cts, .js, or .cjs file
without a panda.config.ts fails with an instruction to rename it, rather than being silently
ignored.
definePandaConfig accepts the complete native Panda configuration (PandaConfig) and adds
Brix's defaults:
presets: Panda's base and default presets, which provide the default tokens, utilities, conditions, and patterns. WhendesignSystemis set, the default is empty because the inherited design system supplies its presets.include:["src/**/*.{js,jsx,ts,tsx}"], the files scanned for style usage.outdir: "styled-system",outExtension: "js", andforceImportExtension: true, so generated modules use explicit.jsimports that Node and bundlers resolve alike.importMap: "#brix/panda"andjsxFramework: "preact".preflight: true, Panda's CSS reset.
Each top-level key you pass replaces its default as a whole; nothing is merged. For example,
include: ["src/**/*.tsx", "stories/**/*.tsx"] stops scanning .ts files unless you list them,
and presets: [myPreset] removes Panda's default tokens and utilities (see
share configuration with presets). A default export that is
a plain object, not wrapped in definePandaConfig, receives none of these defaults. Brix warns
when a configuration omits importMap or jsxFramework, when presets (without
designSystem) omits Panda's base preset, or when include scans nothing under src/. Narrower
globs such as src/components/**/*.tsx and workspace-catalog member globs such as
apps/store/src/**/*.{ts,tsx} count as scanning source directories.
There is no separate on/off switch: Panda is part of every full-stack application and managed
Storybook build. A leftover panda option in defineBrixConfig or the Storybook helpers fails
with Panda is built in; remove the panda option and configure panda.config.ts instead. To keep
an existing CSS reset, set preflight: false; extraction, generated imports, and stylesheet
injection keep working.
Define tokens and semantic tokens
#Tokens are your raw design values; semantic tokens name what a value means in the product, so
components use surface or text instead of copying palette names. Every token leaf is an object
with a value. Semantic tokens reference other tokens with braces, such as {colors.canvas}, and
can vary by condition, such as _dark.
Large themes can live in their own modules. defineTokens and defineSemanticTokens type-check a
token group without needing the whole configuration:
import { defineSemanticTokens, defineTokens } from "brix/panda";
export const tokens = defineTokens({
colors: {
brand: { value: "#0057b8" },
canvas: { value: "#ffffff" },
ink: { value: "#172033" },
},
});
export const semanticTokens = defineSemanticTokens({
colors: {
surface: { value: { base: "{colors.canvas}", _dark: "{colors.ink}" } },
},
});
import { definePandaConfig } from "brix/panda";
import { semanticTokens, tokens } from "./theme/tokens.ts";
export default definePandaConfig({
theme: { extend: { tokens, semanticTokens } },
});
Panda watches modules imported by the configuration, including ones outside src/.
brix/panda also re-exports Panda's configuration types, such as PandaConfig, Tokens,
SemanticTokens, RecipeConfig, and SystemStyleObject, for typing shared helpers.
Extend or replace defaults
#Keys under theme.extend merge with the inherited theme. The same keys directly under theme
replace the inherited values, so theme: { colors: ... } removes Panda's default palette. Reserve
replacement for systems that deliberately own every value.
globalCss, staticCss, conditions, utilities, patterns, hooks, and optimize are
top-level native options. They are not part of theme.
Share configuration with presets
#A preset is reusable configuration: tokens, recipes, conditions, or utilities that several
projects apply. Define one with definePreset, which requires a name. Because presets replaces
the default list, keep Panda's defaults by spreading them from definePandaConfig():
import { definePandaConfig, definePreset } from "brix/panda";
const editorial = definePreset({
name: "editorial",
theme: {
extend: {
textStyles: { lede: { value: { fontSize: "xl", lineHeight: "relaxed" } } },
},
},
});
export default definePandaConfig({
presets: [...(definePandaConfig().presets ?? []), editorial],
});
A preset shares configuration only. It does not carry a library's compiled component CSS; to reuse styled components from a package, inherit its design system instead.
Select dark mode
#A _dark value is an alternate CSS value, not a theme switch. With Panda's default conditions,
dark values apply under an ancestor with the dark class. Your document must set that selector,
for example on the root html element.
To use a different selector, override the condition:
import { definePandaConfig } from "brix/panda";
export default definePandaConfig({
conditions: { extend: { dark: '[data-theme="dark"] &' } },
});
Brix does not provide a runtime theme provider. Decide whether the choice follows a saved user preference or the system preference, and render the initial HTML with the matching selector so the page does not flash from light to dark during load. Browser tests and Storybook previews must apply the same selector to show dark states.
Use responsive values
#Responsive values are objects keyed by breakpoint, applied from that width upward:
import { css } from "#brix/panda/css";
const layout = css({
display: { base: "block", md: "grid" },
gridTemplateColumns: { md: "repeat(2, minmax(0, 1fr))" },
gap: { base: "2", lg: "6" },
});
The default breakpoints are sm (40rem), md (48rem), lg (64rem), xl (80rem), and 2xl
(96rem). Add a breakpoint under theme.extend.breakpoints, such as "3xl": "112rem", using the
same unit as the existing values so Panda can order them correctly.
Write global CSS
#Use globalCss for document-wide rules such as the page background, fonts, and element defaults.
Keep component styles in components, where unused styles are not emitted.
For an !important value that refers to a token, write the reference explicitly:
background: "token(colors.panel)!". The shorthand "panel!" is not resolved as a token and
emits the invalid declaration background: panel !important. Check both light and dark rendered
states after changing global rules.
Use generated utilities
#Brix generates project-specific modules into styled-system/ and you import them through
#brix/panda/*:
import { css } from "#brix/panda/css";
export function BookingCard() {
return (
<article class={css({ display: "grid", gap: "4", padding: "6", borderRadius: "md" })}>
Booking details
</article>
);
}
#brix/panda/css:css,cx, and component-localcvaandsva.#brix/panda/recipes: the recipes and slot recipes registered in the configuration.#brix/panda/patterns: function forms of layout patterns such asstack.#brix/panda/jsx: Preactstyled, pattern components with style props, and recipe contexts.#brix/panda/tokens:token()andtoken.var()for reading token values in code.#brix/panda/types: types such asSystemStyleObject, typed with your tokens; import them withimport type.
The package import map connects the alias to the generated files:
{ "imports": { "#brix/panda/*": "./styled-system/*/index.js" } }
styled-system/ is generated output: keep it ignored in Git and never edit it. brix check,
brix verify, brix test, brix dev, and brix build generate it before they need it, so a
clean checkout needs no separate generation step. If the directory or its types are missing, run
brix check. Type checking during brix check catches imports of missing generated modules or
recipes and undeclared recipe variants; brix doctor checks project structure, not generated
paths.
Change the output directory or alias
#styled-system and #brix/panda are scaffold defaults, not fixed names. Set native outdir and
importMap together with a matching package import. For example, outdir: "design" and
importMap: "#styles" require "#styles/*": "./design/*/index.js".
Then update everything that names the directory: .gitignore, ignorePatterns in your Oxlint
and Oxfmt configurations (the managed defaults ignore only **/styled-system/**), and a library's
files allowlist. brix init and brix upgrade keep an authored mapping.
Development reloads
#- Editing styles in source files updates CSS through hot module replacement, without a reload.
- Editing
panda.config.tsor a module it imports, or creating or deletingpanda.config.ts, regenerates utilities and reloads the page, which resets island state. - Adding or deleting a source file updates extraction automatically.
Continue with component styling.