Layer Setup

CSS @layer configuration for explicit cascade control. Define layer order once, then organize styles without specificity battles.

Overview

CSS Cascade Layers let you control which styles win when there are conflicts, regardless of specificity or source order. Vanilla Breeze uses six layers:

tokens - Design tokens (custom properties)
reset - Baseline normalization
native-elements - Styling for standard HTML elements
custom-elements - CSS-only custom element layouts
web-components - JavaScript-enhanced components
utils - Utility overrides (highest layer precedence)

Layers declared first have lowest precedence. Un-layered styles have the highest precedence.

Visual Diagram

Layer precedence flows from bottom (lowest) to top (highest):

Source Code

Copy this to your main CSS file to establish layer ordering.

/** * CSS Layer Setup * * Establishes the cascade order for Vanilla Breeze styles. * Layers listed first have LOWEST precedence. * Un-layered styles have HIGHEST precedence (use sparingly). */ /* Declare all layers upfront for explicit ordering */ @layer tokens, reset, native-elements, custom-elements, web-components, utils; /* Import each layer's styles */ @import "./tokens/index.css" layer(tokens); @import "./base/reset.css" layer(reset); @import "./native-elements/index.css" layer(native-elements); @import "./custom-elements/index.css" layer(custom-elements); @import "./web-components/index.css" layer(web-components); @import "./utils/index.css" layer(utils);

Usage Examples

Adding Styles to a Layer

Wrap your CSS in a @layer block to place it in the correct layer:

@layer native-elements { button { font-weight: var(--font-weight-medium); } }

Component Overrides

Add component-specific styles to the web-components layer:

@layer web-components { accordion-wc { --accordion-gap: var(--size-m); } }

Utility Classes

Utilities go in the highest-precedence layer to ensure they always apply:

@layer utils { .visually-hidden { position: absolute; clip: rect(0 0 0 0); width: 1px; height: 1px; } .text-center { text-align: center; } }

Layer Purposes

tokens

Design tokens define your visual language - colors, spacing, typography, etc. They're declared as CSS custom properties on :root and have the lowest precedence since they're just variable definitions.

reset

Browser normalization and sensible defaults. Removes inconsistent default styles across browsers and establishes a predictable baseline.

native-elements

Styles for standard HTML elements like <button>, <input>, <table>, etc. These build on the reset with Vanilla Breeze styling conventions.

custom-elements

CSS-only custom elements like <layout-stack>, <layout-grid>, and <layout-card>. These provide layout primitives without JavaScript.

web-components

JavaScript-enhanced components like <accordion-wc>, <tabs-wc>, and <dropdown-wc>. These extend native HTML with interactive behavior.

utils

Utility classes for one-off overrides. Use sparingly - prefer component-level styling. Utilities have the highest layer precedence to ensure they always work.

Why Layers?

Without layers, CSS specificity wars lead to escalating selector complexity or !important abuse. Layers solve this by separating concerns:

Utility classes always override component styles (no !important needed)
Component styles always override base element styles
You can import third-party CSS into lower layers
Source order within a layer still matters, but layer order takes precedence