Cascade Layers

What is @layer?

CSS Cascade Layers are a native browser feature that lets stylesheets declare which bucket their rules belong to. When two selectors have the same specificity, the browser uses layer order to decide which one wins. The key insight: for normal rules, unlayered styles beat layered styles, regardless of selector specificity.

/* Layered — from a component stylesheet */
@layer components {
  .btn { background: var(--primary); }
}

/* Unlayered — your CSS */
.btn { background: tomato; }

/* Result: tomato wins. Always. No !important needed. */

How shadcn-html uses it

Every component CSS file — button, card, dialog, all of them — wraps all of its rules inside a single layer declaration:

@layer components {
  .btn {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    background: var(--primary);
    color: var(--primary-foreground);
    border-radius: var(--radius-md);
    /* ... all button rules ... */
  }

  .btn[data-variant="outline"] {
    background: transparent;
    border: 1px solid var(--border);
  }
}

@layer components {
  .card {
    background-color: var(--card);
    color: var(--card-foreground);
    border: 1px solid var(--border);
    border-radius: var(--radius-xl);
    /* ... all card rules ... */
  }

  .card-header {
    padding: 1.5rem;
  }
}

The design tokens file (default-semantic-tokens.css) is intentionally not layered — token values sit at the top of the cascade so they're always available to both component and user styles.

The cascade order

Here's what the browser sees, from lowest to highest priority:

Because component rules live inside @layer components and your CSS is unlayered, the browser gives your styles higher cascade priority automatically. You never need to out-specify a component selector or reach for !important just to beat a default component rule.

Note: Tokens and your styles are both unlayered — between them, normal specificity and source order apply. Tokens don't compete with your component overrides because they only define :root custom properties, not component selectors.

Overriding component styles

Write your overrides in a regular, unlayered stylesheet. They'll always take precedence.

@layer components {
  .btn {
    border-radius: var(--radius-md);
    font-weight: 500;
    height: 2.25rem;
  }
}

/* Make buttons fully rounded */
.btn {
  border-radius: 9999px;
}

/* Make outline buttons thicker */
.btn[data-variant="outline"] {
  border-width: 2px;
}

Include your override file after the component stylesheets:

<link rel="stylesheet" href="theme/default-semantic-tokens.css">
<link rel="stylesheet" href="components/button/button.css">
<link rel="stylesheet" href="components/card/card.css">

<!-- Your overrides — unlayered, beats the component layer -->
<link rel="stylesheet" href="my-overrides.css">

Using with other CSS frameworks

If you're mixing shadcn-html components with another CSS framework that uses its own @layer declarations, you can declare an explicit layer order at the top of your main stylesheet to control priority:

/* Declare layer order: first listed = lowest priority */
@layer components, utilities;

/* Now framework utilities beat shadcn-html component styles,
   and your unlayered CSS beats everything. */

Without an explicit order declaration, layers are ordered by first appearance in the stylesheet. The explicit declaration gives you full control regardless of import order.

Why not just write unlayered CSS?

Traditional CSS libraries (Bootstrap, Bulma) ship unlayered styles. That creates problems when you try to customize them.

/* Library: high specificity */
.btn.btn-primary { background: blue; }

/* Your override: loses */
.btn { background: tomato; }  /* ✗ */

/* Forced to escalate */
.btn { background: tomato !important; }

/* Library: layered */
@layer components {
  .btn { background: var(--primary); }
}

/* Your override: unlayered */
.btn { background: tomato; }  /* ✓ wins */

/* No !important needed. */

A note on !important: Cascade layers reverse priority for !important rules — an !important declaration inside @layer components actually beats an unlayered !important. This system never uses !important, but be aware of this if you're mixing in third-party CSS that does.

Why not @scope or Web Components?

Shadow DOM creates a styling boundary that makes theming painful — external CSS can't reach inside, so every component needs its own token-plumbing or ::part() surface. SSR is complex, framework interop suffers, and devtools show an extra layer of indirection. @scope strips context from class names, making selectors ambiguous outside their block. Both add abstraction that makes the system harder to read, generate, and modify — for humans and AI alike — so we use neither.

Simplicity isn't a limitation — it's a deliberate design choice. Every pattern in this system was chosen not just to avoid complexity, but to maximize theming flexibility, tooling compatibility, and the context available to AI.

Browser support

@layer is supported in all modern browsers. No polyfill needed.

See caniuse.com/css-cascade-layers and the MDN @layer reference for full details.