Recommendations for use in a Federated Micro-Frontend Archictecture

[mtpetros]

Good morning 👋

TLDR; How can Panda CSS be used effectively in a federated micro-frontend architecture in a way that avoids classname collisions and unpredictable style cascading?

Our requirements/constraints

• Our team develops the design system library (in ReactJS) used by our org.
• Our primary consumer is a federated app architecture. Each feature team has their own app (remote) that is federated by a single host app.
• Each remote can specify the version of our design system library they use, with the result that some remotes can be on version 29, others on version 30 of the design system library, etc.

Problem 1

Each remote is loading the same version of the design system (v1), but remote #2 overrides one of the styles.

/* Remote #1 */
.ds-background {
  background-color: blue;
}

.remote1-background {
  background-color: red;
}

/* Remote #2 */
.ds-background {
  background-color: blue;
}

Solution 1

/* Remote #1 */
@layer ds {                                                                                                                                                                                         
  .ds-background {
    background-color: blue;                                                                                                                                                                         
  }                                                                                                                                                                                                 
}           
                                                                                                                                                                                                    
.remote1-background {                                                                                                                                                                             
  background-color: red;
}

/* Remote #2 */
@layer ds {
  .ds-background {
    background-color: blue;
  }
}

Now the remote overrides win regardless of where design system v1 gets loaded. Unlayered styles always beat layered styles per the CSS cascade spec, so load order between remotes becomes irrelevant.

Problem 2

Each remote is loading a different version of the design system in which some styles have changed between versions.

/* Remote #1 — v1 */
.ds-background {
  background-color: blue;
}

/* Remote #2 — v2 */
.ds-background {
  background-color: green;
}

/* Remote #1 app override */
.remote1-background {
  background-color: red;
}

In this case, adding the design system styles to a layer won't help. Loading order is still going to win within the layer, so remote #1 is going to end up with a green background-color.

This problem is specific to config recipes (defineRecipe), which are the recipe type recommended for design system components. Config recipes generate named component classes (.button, .button--visual-funky) whose names encode the recipe and variant name — but not the CSS declarations. So two versions of the same recipe produce the same class name with different declarations, and the last-loaded version wins globally.

To clarify, atomic recipes (cva) don't have this problem directly, since the CSS value is encoded in the class name itself (e.g. background-color: blue > .bg_blue, background-color: green > .bg_green). However, in a design system components typically reference semantic tokens rather than raw values (bg: 'primary'), which produces .bg_primary { background-color: var(--colors-primary) } — the same atomic class in both versions. The cross-version divergence then surfaces as a :root token collision instead: both versions declare --colors-primary on :root with different values, and the last-loaded declaration wins globally.

Possible Solutions

TLDR;

1- Content-based hashing for css selectors for config recipes
2- Content-based hashing for css variables

I do see that there is a hashing option in the config (https://panda-css.com/docs/concepts/writing-styles#hashing). But it appears the hash is based on the class name itself rather than the CSS declarations. From a single-version design system perspective, name-based hashing makes sense — it gives you stable, cache-friendly identifiers that don't change when a token value is tweaked. But in a federated architecture that supports multiple versions of a design system, a config recipe named button is going to have an identical hash in v1 and v2 even if the declarations differ.

If there was a way to optionally base the hash on the CSS content as well (specifically for config recipes), then the button class from v2 would get a different identifier than v1's and they couldn't interfere with each other. There is precedent for content-based hashing in Vanilla Extract, for example.

A similar argument applies to CSS custom properties. cssVarRoot already exists as a config option and is a great
start — pointing it at a wrapper class (e.g. .mw-provider) scopes token declarations to that subtree rather than
:root, so tokens don't leak globally. But if two versions both declare --colors-primary on .mw-provider, the
last-loaded declaration still wins for every .mw-provider element on the page. Content-based hashing of the variable
names themselves would close that gap — v1 would emit --colors-primary__abc and v2 --colors-primary__xyz, making
collision structurally impossible regardless of load order.

Please let me know if either of this is a possibility for Panda.

Suggestions

Am I thinking through this correctly? Do you have any suggestions on how to successfully use Panda in this arch? Thanks for your help! 👋

[kris-ellery]

A couple questions first, because I think the answer depends heavily on how CSS is produced and loaded in your federation architecture:

• How are you shipping Panda CSS today?
  • Is the design system publishing prebuilt static CSS?
  • Or is it publishing Panda build info/manifests and each federated module generates its own CSS during its app build?

I think those two models have very different isolation characteristics.

If each federated module consumes Panda build info and generates CSS locally, then I think prefix is probably the cleanest solution here. Each remote can namespace its generated selectors + CSS variables independently:

// remote1/panda.config.ts
export default defineConfig({
  prefix: 'remote1',
})

// remote2/panda.config.ts
export default defineConfig({
  prefix: 'remote2',
})

That gives you full separation for:

• generated recipe class names
• utility classes
• semantic token CSS variables

So even if two remotes use different DS versions, they cannot collide because the emitted CSS is structurally isolated.

Something like:

                Design System
             (buildinfo only)
                     |
      --------------------------------
      |                              |
      v                              v

+------------------+       +------------------+
| Remote 1         |       | Remote 2         |
| DS v29           |       | DS v30           |
| prefix=remote1   |       | prefix=remote2   |
+------------------+       +------------------+
| .remote1_button  |       | .remote2_button  |
| --remote1-*      |       | --remote2-*      |
+------------------+       +------------------+
      |                              |
      ------------ Host App ----------

In contrast, if the DS ships shared static CSS artifacts, then prefix probably needs to be version-scoped (ds-v29, ds-v30) because the CSS is no longer generated per remote.

I still think cascade layers are the correct solution for “consumer overrides should always beat DS defaults”, but prefix feels like the missing piece for safe multi-version coexistence.

[mtpetros]

@kris-ellery , thanks for the great response.

How are you shipping Panda CSS today?

Actually, we aren't yet. Right now our implementation is purely hypothetical. We have an existing design library in which Styled Components was the style lib of choice. We have an opportunity to start over at the ground-level and redo some of our original architectural decisions. Panda CSS seems like it could be a great fit. But, we ran into specificity issues / unpredictable cascading with Styled Components in the federated arch that we currently maintain. Before we go all in, we want to work through this issue ahead of time.

If we decided that the design library should ship build info only and put the responsibility on the app for style compilation, we could do this. I've been operating under the assumption that the style library would prebuild styles.

I wonder, beyond the remote scoping, if there is any other advantage to that approach, such as better tree-shaking. What has your experience taught you?

On the other hand, is there any clear advantage to the prefixing of remote app-built css over style library prefixing of prebuilt css?

In this scenario using prebuilt styles:

/* Remote #1 */
@layer ds-v1 {                                                                                                                                                                                         
  .ds-background {
    background-color: blue;                                                                                                                                                                         
  }                                                                                                                                                                                                 
}           
                                                                                                                                                                                                    
.remote1-background {                                                                                                                                                                             
  background-color: red;
}

/* Remote #2 */
@layer ds-v1 {
  .ds-background {
    background-color: blue;
  }
}

/* Remote #3*/
@layer ds-v2 {
  .ds-background {
    background-color: green;
  }
}

If two remotes are on v1 and one on v2, won't their respective version-prefixed classnames still look up the correct styles? And since the DS styles are assigned a layer, remote style overrides still win.

I think the major gotcha with this approach would be ensuring style tokens names/values don't change between major version releases.

Again, this is all hypothetical. It sounds like from your other discussion you have experience using Panda in an enterprise-level production environment.

Thanks for the feedback. This is very helpful.

[Adebesin-Cell]

Hi @kris-ellery @mtpetros,

Wanted to give a heads-up, #3551 adds a guide on using Panda in federated module setups.

Preview: https://panda-docs-4scaa0j2v-chakra-ui.vercel.app/docs/guides/federated-microfrontends

Let me know what you guys think!

[mtpetros]

@Adebesin-Cell , thanks so much. This is fantastic! I really appreciate the time and detail you put into this.

Just some questions for clarification. I'm trying to weigh "ship buildinfo" approach from the "ship static css" approach (ultimately, I think we may do both). It looks like this guide is assuming the remotes are consuming pre-built static CSS from a component library using Panda.

1. Am I correct about that?
2. If so, I noticed the the Panda CSS guides recommend using the "ship buildinfo approach" if both component library and consuming apps are using Panda (https://panda-css.com/docs/guides/component-library#ship-the-build-info-file). Granted, this recommendation probably didn't have a federated architecture mind. Is the "ship buildinfo" a good approach for a federated arch setup?
3. If it is, the prefixing would then be done by the consuming remote as @kris-ellery suggested above, right?

Again, thank you for this. It's very helpful.

[Adebesin-Cell]

@mtpetros, great questions!

1. Yes, the current draft centers the lib-ships-static-CSS case.

2. Ship-buildinfo works just as well for federation. The two shapes differ in where the prefix lives:

Distribution	Who sets prefix	Tradeoff
Lib ships static CSS	Lib author, keyed to DS version (e.g. acme-v1)	One DS bundle per major shared across remotes
Lib ships buildinfo + preset	Remote owner, keyed to remote identity (e.g. remote1)	Each remote tree-shakes its own DS slice; cross-version isolation falls out automatically

panda ship only writes extraction results, not token/recipe definitions, so a buildinfo consumer wires up both the buildinfo and the lib's preset. prefix lives on the consumer's top-level config and is applied at emission, so .button becomes .remote1-button and --colors-brand becomes --remote1-colors-brand regardless of whether the definition came from the consumer or from the lib's preset.

A federated remote's config:

// remote1/panda.config.ts
import { defineConfig } from '@pandacss/dev'
import { acmeDsPreset } from '@acme-org/design-system'

export default defineConfig({
  prefix: 'remote1',
  presets: ['@pandacss/dev/presets', acmeDsPreset],
  importMap: '@acme-org/styled-system',
  include: [
    './node_modules/@acme-org/design-system/dist/panda.buildinfo.json',
    './src/**/*.{ts,tsx}',
  ],
})

If remote1 pins @acme-org/design-system@29 and remote2 pins @30, each remote resolves its own version in node_modules, gets its own preset + buildinfo, and emits CSS under its own remote prefix. Two payloads can't collide on the selector or variable name.

3. Yes, in ship-buildinfo, the prefix is set by the consuming remote. The lib never sets one; each consumer namespaces itself.

Going to expand the guide with both shapes side-by-side.

[Adebesin-Cell]

@mtpetros just pushed the update. The guide now covers both shapes side by side instead of assuming static CSS.

The preview should refresh from the PR shortly. Let me know if anything's unclear or missing. Thank you!

[mtpetros]

Thanks, @Adebesin-Cell . I appreciate the updates! This is very helpful.