How Once UI's cascade layer lets your own CSS and Tailwind utilities override component styles, and what to check in your stylesheets when you upgrade.
From 3.0.0-beta.1, all of Once UI's CSS sits in one cascade layer, so your own CSS and Tailwind utilities override it without !important.
The old fight with specificity
In 2.x, Once UI's stylesheets were plain, unlayered CSS. To change a component's padding or colour from your own stylesheet, you had to match the specificity of Once UI's selector, write a longer one, or reach for !important. That works, but every override becomes a small arms race.
What changed in 3.0
Every stylesheet the packages ship now sits in @layer once-ui. That covers tokens.css, styles.css, and the CSS of each component in core, fx and blocks.The rule that makes this useful: CSS outside any layer beats every layer, whatever its specificity. So your app's own CSS wins by default.That plain .card rule now overrides Once UI's styles on that element. No !important, no extra selector. The same goes for Tailwind utilities.Inside the layer, Once UI's own rules meet by specificity and source order exactly as before, so nothing about how the components look on their own changes.
Try it
3.0 is a pre-release on npm's next tag:
Three things to check when you upgrade
The codemod doesn't touch CSS, so look for these by hand:
An override that used to lose now wins. Usually it's a rule written long ago that never showed because Once UI's style took over. If something suddenly looks different, search your CSS for that selector.
Your !important against Once UI's !important now loses. Inside layers, !important runs the other way. A handful of Once UI declarations use it (on Button, Dialog, EmojiPicker, Input, Switch, Table and link underlines). Drop the !important on yours, since it wins without it.
Your own @layer sits below unlayered CSS too. Its order against Once UI's is the order the layers first appear. To put yours above, declare the order once, before anything loads.
Write this / not this
Do
Avoid
A plain class in your stylesheet
`!important` on every override
Tailwind utilities on the element
Copying Once UI's selector to match it
`@layer once-ui, app;` if you use layers
Leaving your layers' order to chance
Why one layer and not three
The first version split Once UI's CSS into separate tokens, styles and components layers. A visual check caught the problem: a later layer wins over an earlier one regardless of specificity, so a component's display rule beat the token classes that power showIn, and pages showed both the dark and the light image. One layer keeps Once UI's internal cascade as it was and only changes how it meets your CSS.For giving a section its own colours and fonts without writing CSS at all, read the style scope page in this section.
No pages in this collection yet.
/* app.css, not in a layer */
.card {
padding: 0;
}
