Handling Style Overrides with Panda CSS in a Shared UI Component Library

[tongari07]

Hello Panda CSS maintainers,

I am currently using Panda CSS to create a UI component library and have encountered a few issues that I would appreciate your advice on.

Specifically, the Cascade Layer @layer used by Panda CSS is causing problems because it loses specificity to classes outside the layer, leading to styles being overridden by application-level reset CSS and other styles. To address this, I used the --polyfill option to generate CSS without layers, thereby increasing selector specificity.

However, our UI component library is intended to be used across multiple applications, and there are cases where applications need to override styles. Previously, we handled this by accepting a className prop and appending it to the end of the classNames to increase specificity. But with the polyfill approach, application-level class names can no longer override the styles.

Here is a simple example of how we were accepting class names:

export const Heading = ({ children, className, ...rest }) => {
  return (
    <h1 {...rest} className={cx(css({...}), className)}>
      {children}
    </h1>
  );
};

One potential solution we considered is to accept CSSProperties as props and pass them to the element's style attribute. While this allows for style overrides, it does not leverage the benefits of the application's styling library.

Do you have any suggestions or advice on how to address this issue effectively?

Thank you for your assistance.

[adbutterfield]

For the component library I'm building right now based on our company design system, we offer a customization API using props for only certain styles that we want to allow customization. For example, we don't want to allow adding border-radius to text components, but consumers can use any line-height that we have a token defined for. It strikes a nice balance between being open, but still having some constraints so that everything stays aligned with out design system.

Then in the components, we merge the props and the base styles, like:

className={css(someCva.raw({ whateverPropCvaAccepts }), { lineHeight })}

There's a tiny bit of staticCss we need to generate to support this strategy. But the majority of our tokens are used somewhere in a component, so not so much actually.

[cgatian]

Im curious how you get lineHeight props, do you have a single prop on the component lineHeight and just merge that in when it's provided?

[tongari07]

@adbutterfield
Thank you very much!
The proposal is very ideal and an excellent approach. It strikes a great balance between allowing customization and maintaining consistency with the design system.

However, in our company, we have a variety of designs, and considering ease of migration, we need to think about allowing more flexible overrides, not just specific styles. There is a trade-off between prioritizing ease of migration and maintaining design consistency.

We will discuss this within the team.
Thank you.

[adbutterfield]

If you want to have it more open, you could have components accept a css prop that can allow any style supported by your tokens. (We thought about doing this at first, but decided to go more conservative).

Worst case you can allow some inline styles on components, until you can add more tokens/staticCss to support those styles.

[adbutterfield]

@cgatian exactly.

lineHeight is actually a bad example, because our text components have it in the cva. But most of our components accept props for margin (margin + logical margin properties), that consumers can use to position any component we allow to be positionable, which we merge with component styles.

[tongari07]

We ultimately decided to exclude the Cascade Layer in this matter.

Initially, having a Cascade Layer meant that the product-side reset CSS, which wasn't included in the layer, would override our styles.
This is because styles in the Cascade Layer have lower specificity than those outside of the layer.

Here's a simple example to illustrate the issue:

/* Design system styles with Cascade Layer */
@layer utilities {
  .bg-c_blue {
    background-color: blue;
  }

  // ...other styles
}

/* Product-side reset CSS */
button {
  all: unset; // This overrides design system styles
}

To address this, we used the polyfill feature provided by Panda CSS to convert the layer to not(#\#) using postcss-cascade-lalyers. This allowed us to prioritize the design system's styles.

Here's a simple example to illustrate the issue:

/* Design system styles with Cascade Layer */
.bg-c_blue:not(#\#) {
  background-color: blue; // This isn't overridden by the product-side reset CSS
}

/* Product-side reset CSS */
button {
  all: unset;
}

In this setup, the reset CSS would override the design system styles, and the custom class wouldn't apply as expected.
However, this approach prevented us from overriding styles using className.

Here's a simple example to illustrate the issue:

// HTML
<button class="bg-c_blue button_red">Button</button> // Expect to be red, but actual is blue

// CSS
/* Design system styles with not(#\#) */
.bg-c_blue:not(#\#) {
  background-color: blue;
}

/* Product-side custom class */
.button_red {
  background-color: red;
}

To solve this, we used the Panda Integration Hooks to remove :not(#\#) from the generated CSS files. By doing this, we reduced the specificity to a normal level, preventing the reset CSS from overriding our styles and allowing custom classes to override them instead.

Here's how the CSS would look after the change:

// HTML
<button class="bg-c_blue button_red">Button</button> // red

// CSS
/* Design system styles without not(#\#) */
.bg-c_blue {
  background-color: blue;
}

/* Product-side custom class */
.button_red {
  background-color: red;
}

/* Product-side reset CSS */
button {
  all: unset;
}

I hope this solution helps someone facing a similar issue.

However, I believe this method goes against the intended use of layers in Panda CSS and may not be the best approach. If anyone has a better solution, I would love to hear it.