{"id":12097,"library":"stylelint-selector-no-utility","title":"Stylelint Rule: No Utility Selector Styling","description":"This Stylelint rule, `stylelint-selector-no-utility`, is designed to enforce a specific coding standard by disallowing the direct styling of utility classes within CSS. It serves to protect the immutability of single-purpose utility styles, preventing unintended side effects that can arise from altering their definitions. The rule is highly specialized and is intended for use with `@primer/css`, the CSS framework developed by GitHub. The current stable release is version 4.0.0, which was published in March 2019. Due to its close integration with the Primer CSS ecosystem, the package's release cadence is not frequent and is typically tied to updates or changes within Primer CSS itself. Its primary differentiator lies in its targeted application to enforce best practices within a utility-first CSS architecture, specifically for projects utilizing `@primer/css`. It acts as a guardrail against common anti-patterns that can compromise the predictability and maintainability of utility-based styling.","status":"maintenance","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/primer/stylelint-selector-no-utility","tags":["javascript","stylelint-rule","stylelint","url","domain","primer","github","css"],"install":[{"cmd":"npm install stylelint-selector-no-utility","lang":"bash","label":"npm"},{"cmd":"yarn add stylelint-selector-no-utility","lang":"bash","label":"yarn"},{"cmd":"pnpm add stylelint-selector-no-utility","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the rule to function correctly, as it relies on the utility class definitions provided by Primer CSS to identify violations.","package":"@primer/css","optional":false}],"imports":[{"note":"This plugin is loaded via the `plugins` array in a JavaScript-based Stylelint configuration. The rule itself is then enabled and configured under the `rules` section, always prefixed with `primer/`.","symbol":"Plugin registration in stylelint.config.js","correct":"module.exports = { plugins: ['stylelint-selector-no-utility'], rules: { 'primer/selector-no-utility': true } };"},{"note":"When using JSON-based configurations, plugin names are string literals in the `plugins` array, and rules are referenced by their full name (e.g., `primer/selector-no-utility`) in the `rules` object.","wrong":"{\n  \"plugins\": [\n    \"stylelint-selector-no-utility\",\n    \"primer/selector-no-utility\" // Incorrect: plugin list should only contain the package name\n  ]\n}","symbol":"Plugin registration in .stylelintrc.json","correct":"{\n  \"plugins\": [\n    \"stylelint-selector-no-utility\"\n  ],\n  \"rules\": {\n    \"primer/selector-no-utility\": true\n  }\n}"},{"note":"The rule provided by this plugin must always be referenced with the `primer/` prefix in your Stylelint `rules` configuration, even if you are extending a base Primer configuration.","wrong":"rules: { 'selector-no-utility': true }","symbol":"Rule name usage","correct":"rules: { 'primer/selector-no-utility': true }"}],"quickstart":{"code":"{\n  \"plugins\": [\n    \"stylelint-selector-no-utility\"\n  ],\n  \"rules\": {\n    \"primer/selector-no-utility\": true\n  }\n}","lang":"json","description":"This configuration snippet shows how to register the `stylelint-selector-no-utility` plugin and enable its `primer/selector-no-utility` rule in a `.stylelintrc.json` file."},"warnings":[{"fix":"Ensure `@primer/css` (version `>=12`) is installed in your project alongside `stylelint-selector-no-utility`. For example: `npm install @primer/css@^12`.","message":"Starting with v4.0.0, `@primer/css` is a required peer dependency for `stylelint-selector-no-utility` to function correctly. Previous versions might have bundled or relied on specific older versions implicitly.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If using v3.0.1, install `@primer/css@canary`. Otherwise, upgrade to v4.0.0 or later and install the stable `@primer/css` (version `>=12`).","message":"For `stylelint-selector-no-utility` v3.0.1, users were required to install a pre-release (`canary`) version of `@primer/css` due to its migration out of the Primer CSS monorepo.","severity":"breaking","affected_versions":"=3.0.1"},{"fix":"Be aware that the effectiveness and relevance of this rule outside of a Primer CSS context may be limited. Custom adaptations would be required for other utility-first frameworks.","message":"This plugin is highly specific to Primer CSS. While it could be forked or adapted, its built-in logic and checks are tailored to Primer's utility class patterns.","severity":"gotcha","affected_versions":">=3.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `'stylelint-selector-no-utility'` to the `plugins` array in your Stylelint configuration file (e.g., `.stylelintrc.json` or `stylelint.config.js`).","cause":"The stylelint configuration is attempting to use the rule `primer/selector-no-utility` but the plugin `stylelint-selector-no-utility` has not been correctly registered in the `plugins` array.","error":"Unknown rule primer/selector-no-utility"},{"fix":"Install the package using npm or yarn: `npm install --save-dev stylelint-selector-no-utility` or `yarn add --dev stylelint-selector-no-utility`.","cause":"The `stylelint-selector-no-utility` package has not been installed in the project's dependencies.","error":"Error: Cannot find module 'stylelint-selector-no-utility'"},{"fix":"Install the `@primer/css` package: `npm install @primer/css@^12` or `yarn add @primer/css@^12`.","cause":"The required peer dependency `@primer/css` (version `>=12`) is missing from the project's `node_modules`.","error":"A peer dependency of stylelint-selector-no-utility, @primer/css, is not installed."}],"ecosystem":"npm"}