Cascade Layers

Specificity Wars Are Over

Before cascade layers, controlling CSS priority meant managing specificity — adding classes, avoiding IDs, using BEM, fighting !important chains. Layers solve this fundamentally: you declare priority at the architectural level, and specificity becomes irrelevant between layers.

The declaration order of @layer determines priority, not the specificity of selectors within those layers. A single class selector in a higher-priority layer beats an ID+class+element selector in a lower-priority layer.

Declaring and Using Layers

Basic Layer Declaration

/* Declare layer order up front */
@layer reset, base, components, utilities;

/* Fill layers anywhere in your CSS */
@layer reset {
  *, *::before, *::after {
    box-sizing: border-box;
    margin: 0;
  }
}

@layer base {
  body { font-family: system-ui; color: var(--text); }
  a { color: var(--link); }
}

@layer components {
  .card { padding: 1.5rem; border-radius: 8px; }
  .btn { padding: 0.75rem 1.5rem; }
}

@layer utilities {
  .text-center { text-align: center; }
  .mt-4 { margin-top: 1rem; }
}

Priority order: utilities > components > base > reset

Importing Into Layers

/* Put third-party CSS into a layer at import time */
@import 'normalize.css' layer(reset);
@import 'component-library.css' layer(vendor);

/* Declare the full order */
@layer reset, vendor, base, components, utilities;

Anonymous Layers

/* Unnamed layer — can't be appended to later */
@layer {
  .temporary-fix { display: none; }
}

Nested Layers

@layer framework {
  @layer base {
    /* framework.base — lowest in framework */
  }
  @layer components {
    /* framework.components — higher in framework */
  }
}

/* Reference nested layers with dot notation */
@layer framework.base {
  /* Append to the nested layer */
}

Layer Priority Rules

Declared Order = Priority

@layer A, B, C;
/* Priority: C > B > A (last declared wins) */

Unlayered Beats All Layers

@layer base { .btn { color: blue; } }

/* Unlayered — highest priority among normal author styles */
.btn { color: red; } /* This wins */

!important Reverses Layer Order

Normal declarations: last layer wins. !important declarations: first layer wins (priority reverses).

@layer reset, base, utilities;

@layer reset {
  a { color: blue !important; } /* Wins among !important — it's in the first layer */
}

@layer utilities {
  .text-red { color: red !important; } /* Loses to reset's !important */
}

This ensures foundational layers (resets, accessibility) can protect their !important rules from being overridden by higher layers.

Production Architecture with Layers

Recommended Layer Stack

@layer reset, vendor, tokens, base, layouts, components, features, utilities;

@layer reset {
  /* Box-sizing, margin reset, minimal normalization */
}

@layer vendor {
  /* Third-party libraries — contained at low priority */
  @import 'headless-ui.css';
  @import 'syntax-highlighter.css';
}

@layer tokens {
  /* Design tokens as custom properties */
  :root { --color-primary: oklch(0.55 0.19 240); }
}

@layer base {
  /* Element defaults: body, headings, links, lists, tables */
}

@layer layouts {
  /* Page-level layouts: sidebar, grid, holy grail */
}

@layer components {
  /* Reusable components: cards, buttons, modals, forms */
}

@layer features {
  /* Feature-specific styles that override components */
}

@layer utilities {
  /* Utility classes: spacing, alignment, visibility */
}

/* Unlayered: emergency overrides, truly exceptional cases */

Migrating an Existing Codebase

/* Step 1: Wrap existing CSS in a single layer */
@layer legacy {
  @import 'existing-styles.css';
}

/* Step 2: Write new CSS in structured layers above legacy */
@layer legacy, base, components, utilities;

/* Step 3: Gradually move rules from legacy to proper layers */
/* Step 4: Remove empty legacy layer when migration is complete */