) } ``` Since none of the conditions above are statically extractable, Panda will generate css for all possible code path, resulting in a css that looks like this: ```css /* ... */ @layer utilities { .hover\:text_red\.100:where(:hover, [data-hover]) { color: var(--colors-red-100); } .text_red\.200 { color: var(--colors-red-200); } .hover\:text_red\.300:where(:hover, [data-hover]) { color: var(--colors-red-300); } @media screen and (min-width: 768px) { .hover\:md\:text_red\.400:where(:hover, [data-hover]) { color: var(--colors-red-400); } } .text_red\.500 { color: var(--colors-red-500); } .text_red\.600 { color: var(--colors-red-600); } } /* ... */ ``` ## Referenced values Although you should have your styles inlined most of the time, maybe you want to store a value in a variable and re-use in multiple places. This should be fine as long as you keep it statically analyzable. Here's a short list of things to avoid: - Variables that are not defined in the same file - Variables resulting from a function call (e.g. `const color = getColor()`) > If you don't know what value a variable holds with a quick glance, Panda won't be able to either. ```tsx import { css } from '../styled-system/css' // ✅ Good: All values are statically extractable const mainColor = 'red.300' const sizes = { sm: '12px', md: '16px', '2xl': '42px' } const App = () => { return (

) } ``` ### Runtime reference on known objects Using a more complex but still common example : ```tsx import { useState } from 'react' import { css } from '../styled-system/css' const colorByType = { primary: 'red.300', secondary: 'blue.300', tertiary: 'green.300' } const Section = () => { const [type, setType] = useState('primary') // ❌ Avoid: since only "gray.100" is statically extractable here // This will not work as expected, the color CSS won't be generated return

❌ Will not be extracted

} ``` Even though `colorByType` is statically analyzable, Panda does not _yet_ support this kind of automatic extraction fallback. This is the perfect opportunity to use the [recipes](/docs/concepts/recipes). ```tsx import { useState } from 'react' import { cva } from '../styled-system/cva' const sectionRecipe = cva({ base: { color: 'gray.100' }, variants: { type: { primary: { color: 'red.300' }, secondary: { color: 'blue.300' }, tertiary: { color: 'green.300' } } } }) const Section = () => { const [type, setType] = useState('primary') // ✅ Good: This will work as expected return

✅ With a recipe

} ``` Not only did you get the same end result, but you also got a more readable and maintainable code ! You can now : - add more variants to your recipe - add more properties - use a shorthand or a condition All of this with complete type-safety and without having to make drastic changes to the component. > Note that you can also [integrate this recipe directly into your theme](/docs/concepts/recipes) if you want to only > generate the CSS that you use, among other things ## Summary ### What you can do ```tsx // ✅ Good: Conditional styles // ✅ Good: Arbitrary value // ✅ Good: Arbitrary selector span": { color: "red.100" } }} /> // ✅ Good: Runtime value (with config.`staticCss`) const Button = () => { const [color, setColor] = useState('red.300') return } // ✅ Good: Runtime condition // ✅ Good: Referenced value ``` ### What you can't do ```tsx // ❌ Avoid: Runtime value (without config.`staticCss`) const Button = () => { const [color, setColor] = useState('red.300') return } // ❌ Avoid: Referenced value (not statically analyzable or from another file) const CustomCircle = (props) => { const { circleSize = '3' } = props return ( ) } ``` --- ## Federated Micro-Frontends How to safely run multiple Panda-built applications (and multiple versions of the same design system) on a single host page using `prefix` and `cssVarRoot` — whether your design system ships static CSS or build info. Panda supports federated micro-frontend architectures — multiple independently-built apps loaded onto a single host page — through the `prefix` and `cssVarRoot` config options. This guide shows how to set up a Panda lib so it can co-exist with other Panda libs (or with a different version of itself) without class-name or CSS variable collisions. ## When you need this Any setup that loads two or more independently-built Panda stylesheets into one document is affected: - Webpack Module Federation - single-spa, qiankun, or other micro-frontend orchestrators - Dynamically-injected widgets (Intercom-style embeds) - A host page that pins one version of your design system while a remote pins a different version If your bundles never share a document — for example with Next.js multi-zone routing or iframe embedding — you do not need this guide. Each app's CSS loads in its own document and the cascade cannot cross. ## The two classes of clash There are two distinct ways federated bundles collide. ### Override leakage (single version) Two remotes load the same DS version, and one of them defines a local override: ```css /* Remote 1 */ .ds-background { background-color: blue; } .remote1-background { background-color: red; } /* Remote 2 */ .ds-background { background-color: blue; } ``` Load order decides whether `.remote1-background` wins. Wrap your DS rules in a [cascade layer](/docs/concepts/cascade-layers): ```ts filename="panda.config.ts" import { defineConfig } from '@pandacss/dev' export default defineConfig({ layers: { recipes: 'ds.recipes', utilities: 'ds.utilities' } }) ``` Unlayered styles always beat layered styles per the CSS cascade spec, so the remote's local overrides are now deterministic regardless of load order. ### Cross-version collision Remote A pins `@acme/ds@1`, Remote B pins `@acme/ds@2`. Both bundles emit a `.button` rule from `defineRecipe`, and both emit `--colors-brand` on `:root` — with **different** values: ```css /* v1's bundle */ :root { --colors-brand: #ea580c; } .button { background: var(--colors-brand); padding: 8px 12px; } /* v2's bundle */ :root { --colors-brand: #2563eb; } .button { background: var(--colors-brand); padding: 20px 40px; } ``` Same selector, different rule. Same custom property, different value. The cascade picks one globally, and the loser is silently overwritten. **Cascade layers do not help here** — both versions emit into the same `recipes` layer, and within a single layer load order still decides. This is the case `prefix` is designed for. ## Two distribution models `prefix` is the fix in both cases — it's the only thing that survives a cross-version collision. What differs between setups is **who owns the prefix** and **what it's keyed to**, and that follows from how the design system ships its CSS: | Distribution | Who sets `prefix` | Keyed to | Tradeoff | | -------------------------------- | ----------------- | ------------------------------ | --------------------------------------------------------------------------------- | | Lib ships **static CSS** | Lib author | DS version (e.g. `acme-v1`) | One DS bundle per major, shared across every remote | | Lib ships **build info + preset**| Remote owner | Remote identity (e.g. `remote1`) | Each remote tree-shakes its own DS slice; cross-version isolation falls out for free | In the **static-CSS** model the lib runs `panda cssgen` itself and publishes the finished stylesheet, so the prefix has to be baked in at the lib's build time — and the only thing it can safely key to is its own version. The sections from [Setting `prefix`](#setting-prefix) through [Recommended remote config](#recommended-remote-config) walk this model in detail. In the **build-info** model the lib ships extraction metadata and a preset instead of CSS, and each consuming remote generates the final stylesheet during its own app build. The prefix moves to the remote's config, keyed to the remote's identity. See [Model 2: Library ships build info + preset](#model-2-library-ships-build-info--preset) below. > If the lib and every consumer all use Panda, the build-info model is the > one the [Component Library guide](/docs/guides/component-library#ship-the-build-info-file) > already recommends — it tree-shakes the output down to the styles each app > actually uses. Federation doesn't change that recommendation; it just adds > the `prefix` requirement on the consumer side. ## Setting `prefix` Set a distinct `prefix` per design-system version. Panda prepends it to every emitted class name and CSS variable. ```ts filename="panda.config.ts" import { defineConfig } from '@pandacss/dev' export default defineConfig({ prefix: 'acme-v1', preflight: false, theme: { extend: { tokens: { colors: { brand: { value: '#ea580c' } } }, recipes: { button: { className: 'button', base: { background: 'brand', padding: '8px 12px' } } } } } }) ``` After `panda cssgen`, the bundle emits: ```css :where(:root, :host) { --acme-v1-colors-brand: #ea580c; } .acme-v1-button { background: var(--acme-v1-colors-brand); padding: 8px 12px; } ``` A second version with `prefix: 'acme-v2'` emits `.acme-v2-button` and `--acme-v2-colors-brand`. Both bundles can sit in the same `` without clashing — the cascade has nothing to fight over. > **Note:** Source code in the lib and consumer apps doesn't change. Panda's > runtime `css()`, `cva()`, and recipe helpers read `prefix` from config and > emit the namespaced class names automatically. ## Deriving the prefix from your package Hardcoding the prefix is brittle. The robust pattern is to derive it from your package's major version: ```ts filename="panda.config.ts" import { defineConfig } from '@pandacss/dev' import pkg from './package.json' assert { type: 'json' } const major = pkg.version.split('.')[0] const slug = pkg.name.replace(/[@/]/g, '-').replace(/^-/, '') export default defineConfig({ prefix: `${slug}-v${major}`, // ... }) ``` For `@acme/lib@1.4.2`, this produces `acme-lib-v1`. Bumping to a 2.x release automatically rotates the prefix to `acme-lib-v2`, so two majors loaded into the same host page are structurally isolated without any human intervention. > **Note:** Patch and minor releases share a prefix. If you need every > release to be structurally distinct, use the full version > (`acme-lib-v1-4-2`). Major-only is the recommended default — it matches > the granularity humans already reason about for breaking changes. ## Scoping tokens with `cssVarRoot` `prefix` namespaces the CSS variable **names**. That alone is enough to prevent the `:root` collision. If you also want the variables to be **scoped to a subtree** — so tokens declared by one remote don't apply to elements outside its mount point — set `cssVarRoot`: ```ts filename="panda.config.ts" export default defineConfig({ prefix: 'acme-v1', cssVarRoot: '.acme-v1-scope' }) ``` Emitted CSS: ```css .acme-v1-scope { --acme-v1-colors-brand: #ea580c; } ``` The remote then wraps its mount point in an element that carries the class: ```tsx

Mona Sans

Hello World

Hello World