Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Pages and UI / Panda stylingRead Markdown
    On this page

    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:

    panda.config.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). 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
    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
    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
    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:

    panda.config.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:

    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
    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
    { "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.