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.mdindex 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.mdindex 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.```yamlupcoming_change:diff --git a/app/assets/stylesheets/common/base/compose.scss b/app/assets/stylesheets/common/base/compose.scssindex 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.scssindex 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.scssindex 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.scssindex 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.jsonindex 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.yamlindex 85e39ddec54..26ddeeff8e6 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -90,6 +90,9 @@ importers:playwright:specifier: 1.59.1version: 1.59.1+ postcss-selector-parser:+ specifier: ^7.1.4+ version: 7.1.4prettier:specifier: 3.8.1version: 3.8.1diff --git a/stylelint-rules/uc-classes-in-where.mjs b/stylelint-rules/uc-classes-in-where.mjsnew file mode 100644index 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.mjsindex 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.scssindex 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;}