Style components with native Panda
Style Preact components with generated Panda utilities and recipes, share variants across compound components, and publish design systems that applications inherit and rebrand.
Examples use the scaffold's #brix/panda/* alias and assume a configured theme.
Managed React applications do not use this integration; see
the React application boundary.
Choose a styling tool
#css()from#brix/panda/cssfor one-off styles on a single element.cva()andsva()from#brix/panda/cssfor variants owned by one component. They are defined in the component file and compile to atomic classes.- Config recipes, written with
defineRecipeordefineSlotRecipeand registered inpanda.config.ts, for shared components. They get stable class names (button,button--size_compact) and typed generated functions, and they are what a UI library publishes. - Patterns from
#brix/panda/patternsand JSX components from#brix/panda/jsxfor common layouts such asstack,grid, andcontainer.
Add component variants
#cva declares a component's variants next to the component:
import { cva } from "#brix/panda/css";
const badge = cva({
base: { borderRadius: "sm", paddingX: "2", paddingY: "1" },
variants: {
tone: {
info: { backgroundColor: "blue.100", color: "blue.900" },
danger: { backgroundColor: "red.100", color: "red.900" },
},
},
defaultVariants: { tone: "info" },
});
export function Badge({ tone = "info" }: { tone?: "info" | "danger" }) {
return <span class={badge({ tone })}>Status</span>;
}
sva does the same for a multipart component and returns one class per named slot:
import { sva } from "#brix/panda/css";
const field = sva({
slots: ["root", "label"],
base: { root: { display: "grid", gap: "1" }, label: { fontWeight: "medium" } },
});
export function EmailField() {
const classes = field();
return (
<label class={classes.root}>
<span class={classes.label}>Email</span>
<input type="email" name="email" />
</label>
);
}
Share recipes through the configuration
#Colocate a shared recipe with its component:
import { defineRecipe } from "brix/panda";
export const buttonRecipe = defineRecipe({
className: "button",
base: { backgroundColor: "brand", color: "white" },
variants: { size: { compact: { padding: "2" }, standard: { padding: "4" } } },
defaultVariants: { size: "standard" },
});
Register it in the configuration. File names never register recipes on their own:
import { definePandaConfig } from "brix/panda";
import { buttonRecipe } from "./src/components/button/button.recipe.ts";
export default definePandaConfig({
theme: {
extend: {
tokens: { colors: { brand: { value: "#0057b8" } } },
recipes: { button: buttonRecipe },
},
},
});
Components import the generated function and its variant type:
import { button, type ButtonVariantProps } from "#brix/panda/recipes";
export function Button({ size }: ButtonVariantProps) {
return (
<button type="button" class={button({ size })}>
Continue
</button>
);
}
For multipart components, use defineSlotRecipe and register it under
theme.extend.slotRecipes; its generated function returns one class per slot. defineRecipe and
defineSlotRecipe are typed, so type checking rejects default variants and slot styles that the
recipe does not declare.
Share compound-component variants
#A compound component, such as a card group containing cards, can set variant defaults once for
all of its parts. Generated createSlotRecipeContext from #brix/panda/jsx returns
withProvider, withContext, withRootProvider, PropsProvider, and usePropsContext.
Register a config slot recipe and list both the root and the group component in jsx, so Panda
extracts variants passed to either:
import { definePandaConfig, defineSlotRecipe } from "brix/panda";
export default definePandaConfig({
theme: {
extend: {
slotRecipes: {
card: defineSlotRecipe({
className: "card",
slots: ["root", "title"],
jsx: ["CardRoot", "CardGroup"],
variants: {
size: {
small: { root: { padding: "3px" }, title: { fontSize: "11px" } },
large: { root: { padding: "19px" }, title: { fontSize: "23px" } },
},
},
defaultVariants: { size: "small" },
}),
},
},
},
});
import type { ComponentProps } from "brix/preact";
import { createSlotRecipeContext } from "#brix/panda/jsx";
import { card } from "#brix/panda/recipes";
const { withProvider, withContext, PropsProvider, usePropsContext } = createSlotRecipeContext(card);
export const CardRoot = withProvider("section", "root");
export const CardTitle = withContext("h2", "title");
type CardGroupProps = ComponentProps<"div"> & NonNullable<ReturnType<typeof usePropsContext>>;
export function CardGroup(props: CardGroupProps) {
const [variants, rest] = card.splitVariantProps(props);
return (
<PropsProvider value={variants}>
<div {...rest} />
</PropsProvider>
);
}
export function Cards() {
return (
<CardGroup size="large">
<CardRoot>
<CardTitle>Inherits large</CardTitle>
</CardRoot>
<CardRoot size="small">
<CardTitle>Overrides the group</CardTitle>
</CardRoot>
</CardGroup>
);
}
How the pieces behave:
PropsProvidertakes the defaults as itsvalueprop. It supplies variant defaults, not slot styles: parts made withwithContextstill need a root made withwithProviderorwithRootProviderabove them.- A variant set explicitly on a root overrides the group. Passing
undefinedkeeps the group default. usePropsContext()returns the group's values, not a root's local override, and returnsundefinedoutside a group.- These are generated Panda APIs from
#brix/panda/jsx, notbrix/pandaexports. For a single-part config recipe,createRecipeContextofferswithContext,PropsProvider, andusePropsContext.
Wrapping a root does not make Panda track props passed to the wrapper. List each wrapper that
receives variant props in the recipe's jsx, or cover its values with staticCss.
Understand extraction and static CSS
#Panda generates CSS at build time from the style calls it can read in source files. Brix runs the native Vite and Rollup transforms, which also fold static calls into class names and remove runtime styling code that is no longer needed.
A value chosen at runtime, such as a size read from data, is only styled if its CSS was generated.
Cover a finite set of runtime values with staticCss, either on a recipe or at the top level of
the configuration:
import { definePandaConfig } from "brix/panda";
export default definePandaConfig({
staticCss: {
css: [{ properties: { display: ["none", "block", "flex"] }, responsive: true }],
recipes: { button: [{ size: ["compact", "standard"] }] },
},
});
On a recipe, the equivalent is staticCss: [{ size: ["compact", "standard"] }] in
defineRecipe. Wildcards such as ["*"] generate every variant combination, so prefer explicit
lists. Verify dynamic variants in a production build, not only in development.
Publish styled UI libraries
#Create a UI library with brix create ui-library <name>. The scaffold contains a root
panda.config.ts, a tsdown.config.ts that uses defineBrixLibraryBuildConfig from
brix/config, and the package fields a styled library needs:
{
"imports": { "#brix/panda/*": "./styled-system/*/index.js" },
"files": ["dist", "styled-system"]
}
When the library has a panda.config.ts, brix build generates utilities, transforms source,
and emits design-system metadata in dist/panda/: lib.json, preset.mjs, and
buildinfo.json. It also adds native subpath exports to package.json, such as ./panda/*,
./css, and ./recipes, plus a type-only ./types export. Commit and keep those generated
exports next to the main component entry. Source files are not published, and consumers never
compile them.
A design system's types come from ./types, which has no runtime module:
import type { SystemStyleObject } from "brand-ui/types";
Declare every token that the library's recipes reference in the library's own configuration. Those values make the CSS variable references valid, render local previews, and act as defaults that consumers can override. A library cannot rely on a consuming application to define its tokens.
Build the library before consuming it. Local packages can be tested without publishing to a
registry: in a workspace, root brix dev rebuilds libraries in watch mode, and consuming
applications pick up the new output. Libraries without any Panda configuration build as plain
TypeScript packages; a library whose only Panda configuration uses another name, such as
panda.config.mjs, fails brix build, brix check, and brix test with an instruction to rename it
to panda.config.ts. Library builds report the same authored-configuration warnings as
applications.
Extend base → brand → app
#A design system can be layered: a base library provides components, a brand library restyles and
extends it, and an application inherits the brand. Each layer names its parent in designSystem.
A brand library declares base-ui as a runtime dependency and re-exports its components from
the brand's main entry. It may add its own components and recipes:
import { definePandaConfig } from "brix/panda";
export default definePandaConfig({
designSystem: "base-ui",
theme: { extend: { tokens: { colors: { brand: { value: "#8d2386" } } } } },
});
The application depends on brand-ui, imports components from it, and selects it:
import { definePandaConfig } from "brix/panda";
export default definePandaConfig({
designSystem: "brand-ui",
optimize: { treeshakeDesignSystem: true },
theme: { extend: { tokens: { colors: { brand: { value: "#245dce" } } } } },
});
Panda resolves the chain from the root design system down through package dependencies, so each parent must be resolvable from its child. Build in dependency order: base, then brand, then applications and catalogs.
designSystemis always explicit. Adding a styled dependency neither selects it nor combines it with other styled libraries; one configuration inherits one chain.- With
designSystemset, the parent supplies the presets, so the application does not repeat Panda's defaults. optimize.treeshakeDesignSystem(off by default) includes design-system styles only for the exports the application imports. Namespace and side-effect imports still include everything, so check it against your public re-exports and runtime variants.- A preset alone is not a substitute: it shares configuration but carries no compiled component styles.
Token overrides and recipe overrides behave differently. Overriding brand in the
application changes the CSS variable that the published styles reference, so the whole chain
picks up the new value. Recipes are different:
- Recipe usage that Panda extracted from the library's source was compiled when the library was built. A same-named recipe in the application does not rewrite that CSS.
- A library recipe's
staticCssis regenerated against the application's merged recipe, so application overrides do apply to those declarations and can cover variants chosen at runtime. - The library's generated functions keep their published class names and variant keys. Keep
classNameand variant names compatible when overriding a recipe.
Express value-only branding as tokens. For a structural change, create a brand-specific recipe or component instead of overriding the base recipe.
These guarantees cover the published declarations, not the CSS cascade. A Storybook catalog that
also scans a library's source compiles that recipe again under its own configuration and can emit
a competing rule for the same class, so a local authoring story can look different from the
installed package. Keep consumer verification stories importing the built public entry, with
Panda include limited to the consumer's sources, and do not select the library's authoring
stories in that catalog. See the package-consumption story scaffold.
Brix fails preparation when a design system's metadata is missing or reports an error, or when its build info is stale. Rebuild the producers in dependency order after changing them or after upgrading Brix.
Require complete white-label tokens
#Panda lets a child inherit any token it does not override. If every brand must supply a complete set, the design-system library owns that contract:
- Export a strict schema for the required tokens and a typed configuration factory that derives its input type from the schema.
- Validate missing, blank, and unknown keys when the configuration loads.
- Return native
theme.extendtoken overrides, not copies of the producer's recipes. - Keep consumer-only tokens in a separate namespace, so adding a required shared token is a deliberate change that every brand must make.
A complete schema does not prove valid CSS, sufficient contrast, or working layouts; test those separately. Conditions and theme selectors can vary CSS variables at runtime, but Brix does not supply a runtime theme provider.
Migrate existing projects
#Brix releases before native Panda 2 configured styling in src/theme.ts with defineBrixTheme
and generated utilities into .brix/panda/. Move that theme into a root panda.config.ts:
tokens, semantic tokens, and recipes go under theme.extend, while globalCss and staticCss
stay at the top level.
import { definePandaConfig } from "brix/panda";
import { buttonRecipe } from "./src/components/button/button.recipe.ts";
// Before: export const theme = defineBrixTheme({ tokens, recipes, globalCss });
export default definePandaConfig({
theme: {
extend: {
tokens: { colors: { brand: { value: "#0057b8" } } },
recipes: { button: buttonRecipe },
},
},
globalCss: { body: { margin: "0" } },
});
Then complete the migration:
- Delete
src/theme.ts. - Run
brix upgrade. In applications it replaces the old./.brix/panda/*/index.mjsimport target with./styled-system/*/index.js, and it addsstyled-system/to.gitignore. Update a library's#brix/panda/*import by hand, then delete the old.brix/panda/directory. - Remove the
pandaoption fromdefineBrixConfigand the Storybook helpers. A catalog that setthemenow setspandaConfigto the path of a complete Panda configuration, or omits it to use the owner's rootpanda.config.ts; see catalogs. - In each library, remove the
./panda.buildinfo.jsonexport, addstyled-systemtofiles, and rebuild so the native exports are generated. - Set
designSystemin every consumer. Styled dependencies are no longer discovered automatically. - Replace any reliance on recipe rebinding, where an application recipe changed a library's compiled recipe, with token overrides or brand-specific recipes as described in token and recipe overrides.
- Rebuild base libraries, then brand libraries, then applications and catalogs.
Finally, review style ordering. In recipes and globalCss, a later property key wins, including
shorthand and longhand pairs, and textStyle, layerStyle, and animationStyle expand in place.
Put explicit overrides after those compositions. Write important token values as
token(colors.panel)! (see global CSS), and inspect light
and dark rendered states. Version-specific upgrade notes are in
releases and upgrades.
Test and verify
#Run brix doctor, brix check, browser tests, and brix build. Type checks alone do not prove
that CSS is correct: browser component tests receive generated styles automatically, so assert
computed styles for important variants. For a published library, install only the package's
published files in a disposable consumer and check Node imports, declarations, token overrides,
responsive styles, runtime variants, and metadata failures. Run Storybook tests and builds, and
inspect focus, disabled, narrow, wide, and branded states. See testing.