Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
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.
layer-setup.css
/** * 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:
Adding to native-elements layer
@layer native-elements { button { font-weight: var(--font-weight-medium); }}Component Overrides
Add component-specific styles to the web-components layer:
Component customization
@layer web-components { accordion-wc { --accordion-gap: var(--size-m); }}Utility Classes
Utilities go in the highest-precedence layer to ensure they always apply:
Utility classes
@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>, <tab-set>, and <drop-down>. 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
!importantneeded) - 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
Related
Tokens Starter
Design tokens for the tokens layer
Elements
Native and custom element documentation
MDN: @layer
CSS Cascade Layers specification