How it works
Atomic rules
Each top-level key of a style object compiles to an entry of atomic rules. A rule's class name hashes the property, the value as written, the normalised selector and the at-rules, so the same input always gets the same class (margin: 8 and margin: "8px" produce the same CSS under different classes), whether the runtime or the compiler produced it.
Cascade layers
Rules are wrapped in cascade layers k0 to k11: shorthands below mid-level shorthands below longhands, and each nesting level above the one before, up to three levels deep; deeper rules share the third level's layers. Because the layer decides precedence, rules can arrive in any order, from the runtime, from an extracted stylesheet, or both, and composition stays predictable.
Rules in the same layer with equal specificity still fall back to the order they were inserted in. Two nested selectors for one property at the same depth, such as ":hover": { color: "blue" } and ":focus": { color: "red" }, can both match; to decide which wins when they do, add a key for the combination, such as "&:hover:focus", whose selector is more specific.
@layer k0, k1, k2, k3, k4, k5, k6, k7, k8, k9, k10, k11;
@layer k0 {
.koz4kr5 {
padding: 8px 16px;
}
}
@layer k2 {
.kgen44r {
color: white;
}
}
@layer k3 {
.kcs1ml1:hover {
background: #1158c7;
}
}
Unlayered CSS beats layered CSS. Put global and third-party styles in a layer declared before these styles load if the library should win over them. Do not raise specificity or use !important to fight its rules; fix the layer instead.
At runtime
Without the compiler, each style object is compiled as it renders, and its rules are inserted through React's <style href precedence> hoisting. This works in Server Components and Client Components alike, and React deduplicates the rules.
At build time
The compiler compiles the literal parts of css(...), styled(_, {...}) and css={{...}} at build time with the same code the runtime uses, so class names are identical either way. Styles with no runtime part are hoisted to module scope, so a render does no style work for them; those with a runtime part, such as a spread, still merge it on each render. With extract, their rules leave the JavaScript for static stylesheets.
Debugging
- A missing style: check the element has the
k…class, that the rule exists in<style data-precedence="kiln">or in the extracted CSS, and that no unlayered rule overrides it. - To confirm the compiler ran, look in the built JavaScript for precomputed rules such as
@layer k0{.koz4kr5{padding:8px 16px}}, or, withextract, in the CSS. Without the compiler, only the style objects are there.