Skip to content

A platform for community discussion. Free, open, simple.

DEV: Enforce `:where()` for `.uc-*` upcoming-change classes via stylelint (#41917)

David Taylorce04edc1aeb2
diff --git a/.skills/discourse-upcoming-changes-authoring/SKILL.md b/.skills/discourse-upcoming-changes-authoring/SKILL.md
index d3edb58df37..5fbb5eef1f8 100644
--- a/.skills/discourse-upcoming-changes-authoring/SKILL.md
+++ b/.skills/discourse-upcoming-changes-authoring/SKILL.md
@@ -222,6 +222,7 @@ enable_your_feature_name:
#### Key Behaviors
- **Opt-in only**: Omitting `body_class` (or setting it `false`) means no body class — the default. Add it only when you actually have CSS keyed on `uc-{name}`.
+- **Always wrap in `:where()`**: Style the class as `:where(.uc-{name})`, never a bare `.uc-{name}`, so the transitional class adds zero specificity and stays safe to unwrap and delete later — the `discourse/uc-classes-in-where` stylelint rule enforces this.
- **Enabled-for-user gated**: The class only appears for users the change is enabled for (via `currentUserUpcomingChanges`), not globally. Anonymous/ineligible users won't get it.
- **Integrity-checked**: `body_class` is in the integrity spec's `allowed_keys` and must be a boolean — see [Mocking Metadata](#mocking-metadata) for how to set it in tests.
diff --git a/.skills/discourse-upcoming-changes/SKILL.md b/.skills/discourse-upcoming-changes/SKILL.md
index ec4331fa8a3..08705fe3dcd 100644
--- a/.skills/discourse-upcoming-changes/SKILL.md
+++ b/.skills/discourse-upcoming-changes/SKILL.md
@@ -83,7 +83,7 @@ upcoming_change:
| `[specific_groups]` | No one, Specific group(s) |
| `[staff, specific_groups]` | No one, Staff, Specific group(s) |
-**Optional:** Add `include_css: true` if you need to scope CSS to this change. When enabled for a user, a `uc-<dasherized-setting-name>` class is added to `<body>` so stylesheets can gate visuals on the change (e.g. `enable_your_feature_name` → `body.uc-enable-your-feature-name`). Omit it (the default) when the change has no CSS keyed on the body class — body classes are opt-in, not emitted for every change.
+**Optional:** Add `include_css: true` if you need to scope CSS to this change. When enabled for a user, a `uc-<dasherized-setting-name>` class is added to `<body>` so stylesheets can gate visuals on the change (e.g. `enable_your_feature_name` → `body.uc-enable-your-feature-name`). Omit it (the default) when the change has no CSS keyed on the body class — body classes are opt-in, not emitted for every change. Always scope this CSS as `:where(.uc-<dasherized-setting-name>)`, never a bare `.uc-<name>`, so the transitional class adds zero specificity and stays safe to remove later — enforced by the `discourse/uc-classes-in-where` stylelint rule.
```yaml
upcoming_change:
diff --git a/app/assets/stylesheets/common/base/compose.scss b/app/assets/stylesheets/common/base/compose.scss
index fbc574b787b..3f6ec02dba9 100644
--- a/app/assets/stylesheets/common/base/compose.scss
+++ b/app/assets/stylesheets/common/base/compose.scss
@@ -1250,7 +1250,7 @@ body.has-sidebar-page {
}
}
-.uc-enable-composer-redesign {
+:where(.uc-enable-composer-redesign) {
// flat to match the rest of the bar, aligned to the content gutter
#reply-control .reply-to .composer-actions-trigger {
padding-inline-start: 0;
diff --git a/app/assets/stylesheets/common/base/uc-dismiss.scss b/app/assets/stylesheets/common/base/uc-dismiss.scss
index 319f3a7f130..f7a68c8d6dc 100644
--- a/app/assets/stylesheets/common/base/uc-dismiss.scss
+++ b/app/assets/stylesheets/common/base/uc-dismiss.scss
@@ -1,6 +1,6 @@
@use "lib/viewport";
-.uc-floating-dismiss-topics-on-mobile {
+:where(.uc-floating-dismiss-topics-on-mobile) {
@include viewport.until(sm) {
.dismiss-container-top {
position: fixed;
diff --git a/app/assets/stylesheets/common/form-kit/_control-checkbox-upcoming-changes.scss b/app/assets/stylesheets/common/form-kit/_control-checkbox-upcoming-changes.scss
index 4c918156b29..6b1653695a9 100644
--- a/app/assets/stylesheets/common/form-kit/_control-checkbox-upcoming-changes.scss
+++ b/app/assets/stylesheets/common/form-kit/_control-checkbox-upcoming-changes.scss
@@ -1,4 +1,4 @@
-.uc-enable-new-checkbox-style {
+:where(.uc-enable-new-checkbox-style) {
.form-kit {
&__control-checkbox {
/* hide native checkbox */
diff --git a/app/assets/stylesheets/wcag.scss b/app/assets/stylesheets/wcag.scss
index 2d37fea4976..1ac293d3342 100644
--- a/app/assets/stylesheets/wcag.scss
+++ b/app/assets/stylesheets/wcag.scss
@@ -322,7 +322,7 @@ html {
}
// Modernize Foundation Theme specific WCAG overrides
-html.discourse-no-touch .uc-modernize-foundation-theme {
+html.discourse-no-touch :where(.uc-modernize-foundation-theme) {
.btn-default {
.d-icon {
color: var(--d-button-default-icon-color);
@@ -347,7 +347,7 @@ html.discourse-no-touch .uc-modernize-foundation-theme {
}
}
-html .uc-modernize-foundation-theme {
+html :where(.uc-modernize-foundation-theme) {
// Header icons with modernize theme colors
.d-header-icons .d-icon,
.header-sidebar-toggle button .d-icon {
diff --git a/package.json b/package.json
index a9b5cccd18e..2c7fce8ffae 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
"lint-to-the-future": "^3.2.0",
"lint-to-the-future-eslint": "^4.0.0",
"playwright": "1.59.1",
+ "postcss-selector-parser": "^7.1.4",
"prettier": "3.8.1",
"stylelint": "17.5.0",
"typescript": "^5.9.3"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 85e39ddec54..26ddeeff8e6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -90,6 +90,9 @@ importers:
playwright:
specifier: 1.59.1
version: 1.59.1
+ postcss-selector-parser:
+ specifier: ^7.1.4
+ version: 7.1.4
prettier:
specifier: 3.8.1
version: 3.8.1
diff --git a/stylelint-rules/uc-classes-in-where.mjs b/stylelint-rules/uc-classes-in-where.mjs
new file mode 100644
index 00000000000..db298d14d96
--- /dev/null
+++ b/stylelint-rules/uc-classes-in-where.mjs
@@ -0,0 +1,48 @@
+import stylelint from "stylelint";
+import parser from "postcss-selector-parser";
+
+const ruleName = "discourse/uc-classes-in-where";
+
+// `.uc-*` classes are the `uc-<dasherized-setting-name>` body classes emitted
+// for upcoming changes (feature flags with `include_css: true`). They gate
+// transitional CSS for a change and are removed once it becomes permanent, so
+// they must never contribute specificity: every use has to sit inside a
+// `:where()` clause. This keeps the styling safe to unwrap and delete later
+// without leaving behind rules that silently relied on the class's specificity.
+//
+// A `.uc-*` class is allowed only when one of its ancestor nodes is a
+// `:where()` pseudo-class.
+function isInsideWhere(node) {
+ for (let parent = node.parent; parent; parent = parent.parent) {
+ if (parent.type === "pseudo" && parent.value.toLowerCase() === ":where") {
+ return true;
+ }
+ }
+ return false;
+}
+
+export default stylelint.createPlugin(ruleName, (primaryOption) => {
+ return (root, result) => {
+ if (!primaryOption) {
+ return;
+ }
+
+ root.walkRules((rule) => {
+ parser((selectors) => {
+ selectors.walkClasses((classNode) => {
+ if (!classNode.value.startsWith("uc-") || isInsideWhere(classNode)) {
+ return;
+ }
+
+ stylelint.utils.report({
+ message: `Wrap the upcoming-change class ".${classNode.value}" in a :where() clause so it does not contribute specificity`,
+ node: rule,
+ result,
+ ruleName,
+ word: "." + classNode.value,
+ });
+ });
+ }).processSync(rule.selector);
+ });
+ };
+});
diff --git a/stylelint.config.mjs b/stylelint.config.mjs
index 0012ce6e7ec..42361336a34 100644
--- a/stylelint.config.mjs
+++ b/stylelint.config.mjs
@@ -1,11 +1,13 @@
import noCoreVariables from "./stylelint-rules/no-core-variables.mjs";
import requireDesignTokens from "./stylelint-rules/require-design-tokens.mjs";
+import ucClassesInWhere from "./stylelint-rules/uc-classes-in-where.mjs";
export default {
extends: ["@discourse/lint-configs/stylelint"],
- plugins: [noCoreVariables, requireDesignTokens],
+ plugins: [noCoreVariables, requireDesignTokens, ucClassesInWhere],
rules: {
"media-feature-range-notation": "context",
+ "discourse/uc-classes-in-where": true,
},
overrides: [
{
diff --git a/themes/horizon/common/color_definitions.scss b/themes/horizon/common/color_definitions.scss
index a240709a47f..eb37788ec7f 100644
--- a/themes/horizon/common/color_definitions.scss
+++ b/themes/horizon/common/color_definitions.scss
@@ -103,6 +103,6 @@ html {
--discourse_id-border: var(--discourse_id-background) !important;
}
-.uc-modernize-foundation-theme {
+:where(.uc-modernize-foundation-theme) {
--d-sidebar-active-background: var(--d-selected) !important;
}