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

# 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](/docs/styling-theme.md).
Managed React applications do not use this integration; see
[the React application boundary](/docs/react-managed.md#understand-the-application-boundary).

## Choose a styling tool

- `css()` from `#brix/panda/css` for one-off styles on a single element.
- `cva()` and `sva()` from `#brix/panda/css` for variants owned by one component. They are
  defined in the component file and compile to atomic classes.
- Config recipes, written with `defineRecipe` or `defineSlotRecipe` and registered in
  `panda.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/patterns` and JSX components from `#brix/panda/jsx` for common
  layouts such as `stack`, `grid`, and `container`.

## Add component variants

`cva` declares a component's variants next to the component:

`src/components/Badge.tsx`

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

`src/components/Field.tsx`

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

`src/components/button/button.recipe.ts`

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

`panda.config.ts`

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

`src/components/button/Button.tsx`

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

`panda.config.ts`

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

```

`src/components/Card.tsx`

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

- `PropsProvider` takes the defaults as its `value` prop. It supplies variant defaults, **not
  slot styles**: parts made with `withContext` still need a root made with `withProvider` or
  `withRootProvider` above them.
- A variant set explicitly on a root overrides the group. Passing `undefined` keeps the group
  default.
- `usePropsContext()` returns the group's values, not a root's local override, and returns
  `undefined` outside a group.
- These are generated Panda APIs from `#brix/panda/jsx`, not `brix/panda` exports. For a
  single-part config recipe, `createRecipeContext` offers `withContext`, `PropsProvider`, and
  `usePropsContext`.

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:

`panda.config.ts`

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

`package.json`

```json
{
  "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:

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

`panda.config.ts`

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

`panda.config.ts`

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

- `designSystem` is always explicit. Adding a styled dependency neither selects it nor combines
  it with other styled libraries; one configuration inherits one chain.
- With `designSystem` set, 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 `staticCss` is 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
  `className` and 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](/docs/storybook-stories.md#test-a-built-package-in-a-consumer).

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.extend` token 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.

`panda.config.ts`

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

1. Delete `src/theme.ts`.
1. Run `brix upgrade`. In applications it replaces the old `./.brix/panda/*/index.mjs` import
   target with `./styled-system/*/index.js`, and it adds `styled-system/` to `.gitignore`. Update
   a library's `#brix/panda/*` import by hand, then delete the old `.brix/panda/` directory.
1. Remove the `panda` option from `defineBrixConfig` and the Storybook helpers. A catalog that set
   `theme` now sets `pandaConfig` to the path of a complete Panda configuration, or omits it to use
   the owner's root `panda.config.ts`; see [catalogs](/docs/storybook-catalogs.md).
1. In each library, remove the `./panda.buildinfo.json` export, add `styled-system` to `files`,
   and rebuild so the native exports are generated.
1. Set `designSystem` in every consumer. Styled dependencies are no longer discovered
   automatically.
1. 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](#extend-base-brand-app).
1. 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](/docs/styling-theme.md#write-global-css)), and inspect light
and dark rendered states. Version-specific upgrade notes are in
[releases and upgrades](/docs/releases-upgrades.md).

## 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](/docs/testing.md).
