> [Agent navigation index](/llms.txt)

# 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](/docs/react-managed.md#understand-the-application-boundary).

## Create the configuration

Add a root `panda.config.ts` that default-exports `definePandaConfig` from `brix/panda`:

`panda.config.ts`

```ts
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. When `designSystem` is 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"`, and `forceImportExtension: true`, so
  generated modules use explicit `.js` imports that Node and bundlers resolve alike.
- `importMap: "#brix/panda"` and `jsxFramework: "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](#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:

`theme/tokens.ts`

```ts
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}" } },
  },
});

```

`panda.config.ts`

```ts
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()`:

`panda.config.ts`

```ts
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](/docs/styling-components.md#extend-base-brand-app)
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:

`panda.config.ts`

```ts
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:

```tsx
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/*`:

`src/features/booking/BookingCard.tsx`

```tsx
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-local `cva` and `sva`.
- `#brix/panda/recipes`: the recipes and slot recipes registered in the configuration.
- `#brix/panda/patterns`: function forms of layout patterns such as `stack`.
- `#brix/panda/jsx`: Preact `styled`, pattern components with style props, and recipe contexts.
- `#brix/panda/tokens`: `token()` and `token.var()` for reading token values in code.
- `#brix/panda/types`: types such as `SystemStyleObject`, typed with your tokens; import them
  with `import type`.

The package import map connects the alias to the generated files:

`package.json`

```json
{ "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.ts` or a module it imports, or creating or deleting `panda.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](/docs/styling-components.md).
