Stylelint Rule: No Utility Selector Styling

4.0.0 · maintenance · verified Sun Apr 19

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.

Common errors

```
Unknown rule primer/selector-no-utility
```
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.

fix Add `'stylelint-selector-no-utility'` to the `plugins` array in your Stylelint configuration file (e.g., `.stylelintrc.json` or `stylelint.config.js`).
```
Error: Cannot find module 'stylelint-selector-no-utility'
```
cause The `stylelint-selector-no-utility` package has not been installed in the project's dependencies.

fix Install the package using npm or yarn: `npm install --save-dev stylelint-selector-no-utility` or `yarn add --dev stylelint-selector-no-utility`.
```
A peer dependency of stylelint-selector-no-utility, @primer/css, is not installed.
```
cause The required peer dependency `@primer/css` (version `>=12`) is missing from the project's `node_modules`.

fix Install the `@primer/css` package: `npm install @primer/css@^12` or `yarn add @primer/css@^12`.

Warnings

breaking 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.
Fix: Ensure `@primer/css` (version `>=12`) is installed in your project alongside `stylelint-selector-no-utility`. For example: `npm install @primer/css@^12`.
breaking 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.
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`).
gotcha 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.
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.

Install

npm install stylelint-selector-no-utility npm
yarn add stylelint-selector-no-utility yarn
pnpm add stylelint-selector-no-utility pnpm

Imports

Plugin registration in stylelint.config.js
```
module.exports = { plugins: ['stylelint-selector-no-utility'], rules: { 'primer/selector-no-utility': true } };
```
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/`.

Plugin registration in .stylelintrc.json

wrong:

{
  "plugins": [
    "stylelint-selector-no-utility",
    "primer/selector-no-utility" // Incorrect: plugin list should only contain the package name
  ]
}

correct:

{
  "plugins": [
    "stylelint-selector-no-utility"
  ],
  "rules": {
    "primer/selector-no-utility": true
  }
}

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.

Rule name usage
wrong:
```
rules: { 'selector-no-utility': true }
```
correct:
```
rules: { 'primer/selector-no-utility': true }
```
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.

Quickstart

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.

{
  "plugins": [
    "stylelint-selector-no-utility"
  ],
  "rules": {
    "primer/selector-no-utility": true
  }
}

view raw JSON →