From d6fe9f78190cc3b48c26b8e76e25674a03c70bce Mon Sep 17 00:00:00 2001
From: Lindsay M <126139086+lindsaym-fa@users.noreply.github.com>
Date: Wed, 19 Nov 2025 17:43:55 -0500
Subject: [PATCH] Define and import cascade layers (#1793)

* define cascade layers

* invoke cascade layers in kitchen sink styles

* invoke cascade layers in utilities and native styles

* invoke cascade layers in palettes + consolidate shared palette rules

* invoke cascade layers in themes

* add changelog

* prettier demands whitespace
---
 packages/webawesome/docs/docs/resources/changelog.md       | 1 +
 packages/webawesome/src/styles/color/palettes/base.css     | 4 ++++
 packages/webawesome/src/styles/color/palettes/bright.css   | 1 -
 packages/webawesome/src/styles/color/palettes/default.css  | 1 -
 packages/webawesome/src/styles/color/palettes/shoelace.css | 1 -
 packages/webawesome/src/styles/layers.css                  | 2 ++
 packages/webawesome/src/styles/native.css                  | 3 +++
 packages/webawesome/src/styles/themes/awesome.css          | 1 +
 packages/webawesome/src/styles/themes/default.css          | 1 +
 packages/webawesome/src/styles/themes/shoelace.css         | 1 +
 packages/webawesome/src/styles/utilities.css               | 2 ++
 packages/webawesome/src/styles/webawesome.css              | 7 ++++---
 12 files changed, 19 insertions(+), 6 deletions(-)
 create mode 100644 packages/webawesome/src/styles/layers.css

diff --git a/packages/webawesome/docs/docs/resources/changelog.md b/packages/webawesome/docs/docs/resources/changelog.md
index 513432106..8bd78fecd 100644
--- a/packages/webawesome/docs/docs/resources/changelog.md
+++ b/packages/webawesome/docs/docs/resources/changelog.md
@@ -13,6 +13,7 @@ Components with the <wa-badge variant="warning">Experimental</wa-badge> badge sh
 
 ## Next
 
+- Added `layers.css` to define cascade layer order and updated palettes, themes, native styles, and utilities to import the new rule for more fail-safe modularity [pr:1793]
 - Fixed a bug in `<wa-slider>` that caused some touch devices to end up with the incorrect value [issue:1703]
 - Fixed a bug in `<wa-card>` that prevented some slots from being detected correctly [discuss:1450]
 - Fixed a z-index bug in `<wa-scroller>` styles [issue:1724]
diff --git a/packages/webawesome/src/styles/color/palettes/base.css b/packages/webawesome/src/styles/color/palettes/base.css
index 88cc20294..7e8151185 100644
--- a/packages/webawesome/src/styles/color/palettes/base.css
+++ b/packages/webawesome/src/styles/color/palettes/base.css
@@ -1,3 +1,7 @@
+/* Rules shared by all palettes */
+@import url('../../layers.css');
+@import url('../variants.css');
+
 /* Generates --wa-color-{hue}-on tokens for pairing with any palette's key colors */
 :where(:root),
 :host {
diff --git a/packages/webawesome/src/styles/color/palettes/bright.css b/packages/webawesome/src/styles/color/palettes/bright.css
index 120196805..a23c70560 100644
--- a/packages/webawesome/src/styles/color/palettes/bright.css
+++ b/packages/webawesome/src/styles/color/palettes/bright.css
@@ -1,5 +1,4 @@
 @import url('base.css');
-@import url('../variants.css');
 
 @layer wa-color-palette {
   .wa-palette-bright {
diff --git a/packages/webawesome/src/styles/color/palettes/default.css b/packages/webawesome/src/styles/color/palettes/default.css
index af9d6ffc3..87c5b9dc2 100644
--- a/packages/webawesome/src/styles/color/palettes/default.css
+++ b/packages/webawesome/src/styles/color/palettes/default.css
@@ -1,5 +1,4 @@
 @import url('base.css');
-@import url('../variants.css');
 
 @layer wa-color-palette {
   :where(:root),
diff --git a/packages/webawesome/src/styles/color/palettes/shoelace.css b/packages/webawesome/src/styles/color/palettes/shoelace.css
index c0ff6257f..c41cdc135 100644
--- a/packages/webawesome/src/styles/color/palettes/shoelace.css
+++ b/packages/webawesome/src/styles/color/palettes/shoelace.css
@@ -1,5 +1,4 @@
 @import url('base.css');
-@import url('../variants.css');
 
 @layer wa-color-palette {
   .wa-palette-shoelace,
diff --git a/packages/webawesome/src/styles/layers.css b/packages/webawesome/src/styles/layers.css
new file mode 100644
index 000000000..e6bcef7f0
--- /dev/null
+++ b/packages/webawesome/src/styles/layers.css
@@ -0,0 +1,2 @@
+/* Order of precedence for all cascade layers in Web Awesome */
+@layer wa-native, wa-utilities, wa-color-palette, wa-color-variant, wa-theme, wa-theme-dimension, wa-theme-overrides;
diff --git a/packages/webawesome/src/styles/native.css b/packages/webawesome/src/styles/native.css
index ae1d6d6d0..70d1ff509 100644
--- a/packages/webawesome/src/styles/native.css
+++ b/packages/webawesome/src/styles/native.css
@@ -1,3 +1,6 @@
+@import url('layers.css');
+
+/* Required utilities */
 @import url('utilities/size.css');
 @import url('utilities/variants.css');
 
diff --git a/packages/webawesome/src/styles/themes/awesome.css b/packages/webawesome/src/styles/themes/awesome.css
index b0bd11d83..47ce9a4c2 100644
--- a/packages/webawesome/src/styles/themes/awesome.css
+++ b/packages/webawesome/src/styles/themes/awesome.css
@@ -1,3 +1,4 @@
+@import url('../layers.css');
 @import url('../color/palettes/bright.css'); /* To use this palette, add class="wa-palette-bright" to the <html> element */
 @import url('https://fonts.bunny.net/css2?family=Crimson+Pro:ital,wght@0,200..900;1,200..900&family=Quicksand:wght@300..700&display=swap');
 
diff --git a/packages/webawesome/src/styles/themes/default.css b/packages/webawesome/src/styles/themes/default.css
index 8cd6b15c9..0cdc87885 100644
--- a/packages/webawesome/src/styles/themes/default.css
+++ b/packages/webawesome/src/styles/themes/default.css
@@ -1,3 +1,4 @@
+@import url('../layers.css');
 @import url('../color/palettes/default.css');
 
 @layer wa-theme {
diff --git a/packages/webawesome/src/styles/themes/shoelace.css b/packages/webawesome/src/styles/themes/shoelace.css
index a9ef60a0b..50c72ab51 100644
--- a/packages/webawesome/src/styles/themes/shoelace.css
+++ b/packages/webawesome/src/styles/themes/shoelace.css
@@ -1,3 +1,4 @@
+@import url('../layers.css');
 @import url('../color/palettes/shoelace.css'); /* To use this palette, add class="wa-palette-shoelace" to the <html> element */
 
 @layer wa-theme {
diff --git a/packages/webawesome/src/styles/utilities.css b/packages/webawesome/src/styles/utilities.css
index 8fdea0f71..d80c3d18e 100644
--- a/packages/webawesome/src/styles/utilities.css
+++ b/packages/webawesome/src/styles/utilities.css
@@ -1,3 +1,5 @@
+@import url('layers.css');
+
 @import url('utilities/fouce.css');
 @import url('utilities/visually-hidden.css');
 @import url('utilities/scroll-lock.css');
diff --git a/packages/webawesome/src/styles/webawesome.css b/packages/webawesome/src/styles/webawesome.css
index 0ff8dc0ac..8c1d3a189 100644
--- a/packages/webawesome/src/styles/webawesome.css
+++ b/packages/webawesome/src/styles/webawesome.css
@@ -1,9 +1,10 @@
-@layer wa-native, wa-utilities, wa-color-palette, wa-color-variant, wa-theme, wa-theme-dimension, wa-theme-overrides;
+/* Cascade layers */
+@import url('layers.css');
 
-/* Native Styles */
+/* Native styles */
 @import url('native.css');
 
-/* CSS Utilities */
+/* CSS utilities */
 @import url('utilities.css');
 
 /* Theme */