@primer/stylelint-config 12.4.2 → 12.5.0-rc.d5df50d

package/CHANGELOG.md

@@ -0,0 +1,258 @@
+# Changelog
+
+## 12.5.0
+
+### Minor Changes
+
+- [#262](https://github.com/primer/stylelint-config/pull/262) [`28a4086`](https://github.com/primer/stylelint-config/commit/28a4086e8c781f76494c7e77b9437046a6f686a6) Thanks [@jonrohan](https://github.com/jonrohan)! - Writing a primer/utilities plugin to look for code that duplicates utilities
+
+## 12.4.2
+
+### Patch Changes
+
+- [#258](https://github.com/primer/stylelint-config/pull/258) [`fa48eed`](https://github.com/primer/stylelint-config/commit/fa48eed1af84474fa49bdb7ec861d2c6a3210239) Thanks [@jonrohan](https://github.com/jonrohan)! - Fixing dependencies
+
+* [#260](https://github.com/primer/stylelint-config/pull/260) [`4f42328`](https://github.com/primer/stylelint-config/commit/4f4232826cd3055e0e9dc49ff16925c47db21863) Thanks [@jonrohan](https://github.com/jonrohan)! - Turning off 'function-no-unknown': null,
+
+## 12.4.1
+
+### Patch Changes
+
+- [#256](https://github.com/primer/stylelint-config/pull/256) [`37eb1cb`](https://github.com/primer/stylelint-config/commit/37eb1cbd342590f4c43e37779f657a4b19594eca) Thanks [@jonrohan](https://github.com/jonrohan)! - Remove stylelint peer
+
+## 12.4.0
+
+### Minor Changes
+
+- [#232](https://github.com/primer/stylelint-config/pull/232) [`27ddfc9`](https://github.com/primer/stylelint-config/commit/27ddfc98f93ed898552bb62aa0926d35497dda72) Thanks [@jonrohan](https://github.com/jonrohan)! - Creating a responsive-widths plugin to keep fixed widths smaller than the minimum viewport size
+
+* [#253](https://github.com/primer/stylelint-config/pull/253) [`0edeee0`](https://github.com/primer/stylelint-config/commit/0edeee07b1e7ef51bcd0942c65d98131ac384887) Thanks [@jonrohan](https://github.com/jonrohan)! - Changing this peerDependency to be any
+
+## 12.3.3
+
+### Patch Changes
+
+- [#218](https://github.com/primer/stylelint-config/pull/218) [`c03be7d`](https://github.com/primer/stylelint-config/commit/c03be7da1126123c079d86e00a2158a913e015f8) Thanks [@jonrohan](https://github.com/jonrohan)! - [Bug fix] Catching values with dots in them
+
+* [#217](https://github.com/primer/stylelint-config/pull/217) [`5bb2834`](https://github.com/primer/stylelint-config/commit/5bb28342a6194dfdd4fbf5197682367ea54792b7) Thanks [@jsoref](https://github.com/jsoref)! - Spelling fixes
+
+## 12.3.2
+
+### Patch Changes
+
+- [#215](https://github.com/primer/stylelint-config/pull/215) [`66b16ae`](https://github.com/primer/stylelint-config/commit/66b16ae2edd81f8c8949f83c96d7011e5d395cc0) Thanks [@jonrohan](https://github.com/jonrohan)! - Making linter pick up separate function groups
+
+## 12.3.1
+
+### Patch Changes
+
+- [#213](https://github.com/primer/stylelint-config/pull/213) [`2a27f86`](https://github.com/primer/stylelint-config/commit/2a27f86868b1f4717100a1f0897cdaefb1dd6be7) Thanks [@jonrohan](https://github.com/jonrohan)! - Fixing an issue where the new spacing plugin isn't traversing child sectors.
+
+## 12.3.0
+
+### Minor Changes
+
+- [#191](https://github.com/primer/stylelint-config/pull/191) [`71c7985`](https://github.com/primer/stylelint-config/commit/71c79853b679b674c1d27686f8d2168660b24a45) Thanks [@jonrohan](https://github.com/jonrohan)! - Refactoring the primer/spacing plugin to better match results
+
+## 12.2.0
+
+### Minor Changes
+
+- [#170](https://github.com/primer/stylelint-config/pull/170) [`b56fcd1`](https://github.com/primer/stylelint-config/commit/b56fcd1bce90d2e3e1621ef7af7545c52c935579) Thanks [@jonrohan](https://github.com/jonrohan)! - Moving config from primer/css's [stylelint.config.cjs](https://github.com/primer/css/blob/c65be7f0c8b0fb6e1ba406b5d35c6073df161a33/stylelint.config.cjs) file to this package.
+
+* [#168](https://github.com/primer/stylelint-config/pull/168) [`d6ff2b9`](https://github.com/primer/stylelint-config/commit/d6ff2b94ff0d309c1b79e783e6ee1b2f87a375ff) Thanks [@jonrohan](https://github.com/jonrohan)! - Extending stylelint-config-standard and removing defaults
+
+- [#170](https://github.com/primer/stylelint-config/pull/170) [`b56fcd1`](https://github.com/primer/stylelint-config/commit/b56fcd1bce90d2e3e1621ef7af7545c52c935579) Thanks [@jonrohan](https://github.com/jonrohan)! - Adding config from the [stylelint-scss recommended config](https://github.com/stylelint-scss/stylelint-config-recommended-scss/blob/82d51c399ddaa2f9d282e419399dd2028f47830c/index.js).
+
+### Patch Changes
+
+- [#181](https://github.com/primer/stylelint-config/pull/181) [`23e438a`](https://github.com/primer/stylelint-config/commit/23e438a7a9062550baa696cafbb186dc78b723f5) Thanks [@jonrohan](https://github.com/jonrohan)! - Turning off scss/dollar-variable-default
+
+## 12.1.1
+
+### Patch Changes
+
+- [#161](https://github.com/primer/stylelint-config/pull/161) [`48c4afc`](https://github.com/primer/stylelint-config/commit/48c4afc1913863136d62967653697323f8da57b7) Thanks [@dependabot](https://github.com/apps/dependabot)! - Bump @primer/primitives from 6.1.0 to 7.0.1
+
+## 12.1.0
+
+### Minor Changes
+
+- [#150](https://github.com/primer/stylelint-config/pull/150) [`4af1647`](https://github.com/primer/stylelint-config/commit/4af16474148d96fba5567068280a9ffe6e7a80ba) Thanks [@jonrohan](https://github.com/jonrohan)! - Making all be first in property order
+
+* [#151](https://github.com/primer/stylelint-config/pull/151) [`d7c8b2b`](https://github.com/primer/stylelint-config/commit/d7c8b2b908b113fa14c7637dfced34610a3bcfac) Thanks [@jonrohan](https://github.com/jonrohan)! - Adding [string-quotes](https://stylelint.io/user-guide/rules/list/string-quotes) rule to config
+
+### Patch Changes
+
+- [#146](https://github.com/primer/stylelint-config/pull/146) [`214362c`](https://github.com/primer/stylelint-config/commit/214362c0e3c9449a5ff7d3bd047018493043d3c0) Thanks [@dependabot](https://github.com/apps/dependabot)! - Bump @primer/css from 13.2.0 to 16.3.0
+
+## 12.0.1
+
+### Patch Changes
+
+- [#132](https://github.com/primer/stylelint-config/pull/132) [`b672367`](https://github.com/primer/stylelint-config/commit/b6723679606bb8d39e75025ae17ace9f1c3e2631) Thanks [@jonrohan](https://github.com/jonrohan)! - Updating no-deprecated-colors plugin for edge cases
+
+## 12.0.0
+
+### Major Changes
+
+- [#129](https://github.com/primer/stylelint-config/pull/129) [`653d596`](https://github.com/primer/stylelint-config/commit/653d596072b897b265b093aac4cd5c143e61410e) Thanks [@jonrohan](https://github.com/jonrohan)! - Renaming the package to use org scope. This is a breaking change, you'll need to uninstall `stylelint-config-primer` and reinstall `@primer/stylelint-config`.
+
+### Patch Changes
+
+- [#130](https://github.com/primer/stylelint-config/pull/130) [`f495a56`](https://github.com/primer/stylelint-config/commit/f495a563a9e809252630466088eb94177e6c0be4) Thanks [@jonrohan](https://github.com/jonrohan)! - Updating @primer/primitives to 5.0 release candidate
+
+## 11.1.1
+
+### Patch Changes
+
+- [`3a4654b`](https://github.com/primer/stylelint-config/commit/3a4654b1b7920d71e1284ff78a3bedff932e66a3) [#111](https://github.com/primer/stylelint-config/pull/111) Thanks [@jonrohan](https://github.com/jonrohan)! - Fixing the primer/colors and primer/borders rules
+
+## 11.1.0
+
+### Minor Changes
+
+- [`e83f61c`](https://github.com/primer/stylelint-config/commit/e83f61cef3bf1df1d9420662594040efdcb86c89) [#99](https://github.com/primer/stylelint-config/pull/99) Thanks [@jonrohan](https://github.com/jonrohan)! - Create a `no-deprecated-colors` rule that looks for deprecated css color variables from primer/primitives.
+
+### Patch Changes
+
+- [`581f40a`](https://github.com/primer/stylelint-config/commit/581f40a4aacb45db5426b82d4a2434e81eb032e2) [#105](https://github.com/primer/stylelint-config/pull/105) Thanks [@jonrohan](https://github.com/jonrohan)! - Adding reporting to the linter to know how many variables are replaced
+
+## 10.0.1
+
+### Patch Changes
+
+- [`aa76171`](https://github.com/primer/stylelint-config/commit/aa76171fc5c9c308fcd9d7f7285c8fbdb2c18a7b) [#90](https://github.com/primer/stylelint-config/pull/90) Thanks [@jonrohan](https://github.com/jonrohan)! - Updating the no-undefined-variables lint for the new color-variables mixin.
+
+## 10.0.0
+
+### Major Changes
+
+- [`23a1f15`](https://github.com/primer/stylelint-config/commit/23a1f1599673f2a4f9f28c39da61f42871c05697) [#85](https://github.com/primer/stylelint-config/pull/85) Thanks [@koddsson](https://github.com/koddsson)! - Replace deprecated "blacklist" rules for "disallow list" rules.
+
+  See https://stylelint.io/user-guide/rules/at-rule-blacklist and http://stylelint.io/user-guide/rules/declaration-property-value-disallowed-list/
+
+### Patch Changes
+
+- [`40d9bb8`](https://github.com/primer/stylelint-config/commit/40d9bb867194ae4335846953b5d8706dc7dc7d79) [#86](https://github.com/primer/stylelint-config/pull/86) Thanks [@koddsson](https://github.com/koddsson)! - Allow rules to optionally display a URL with their message.
+
+## 9.3.3
+
+### Patch Changes
+
+- [`a339c69`](https://github.com/primer/stylelint-config/commit/a339c698b9ba7ccd01b8cb773dad7a3a14dd13a1) [#81](https://github.com/primer/stylelint-config/pull/81) Thanks [@BinaryMuse](https://github.com/BinaryMuse)! - Update globby to v11
+
+## 9.3.2
+
+### Patch Changes
+
+- [`d18cfbf`](https://github.com/primer/stylelint-config/commit/d18cfbfefc25be6ae38f73132552d2f3c62c4d02) [#79](https://github.com/primer/stylelint-config/pull/79) Thanks [@BinaryMuse](https://github.com/BinaryMuse)! - Add additional verbose logging to `no-undefined-vars`
+
+* [`d18cfbf`](https://github.com/primer/stylelint-config/commit/d18cfbfefc25be6ae38f73132552d2f3c62c4d02) [#79](https://github.com/primer/stylelint-config/pull/79) Thanks [@BinaryMuse](https://github.com/BinaryMuse)! - Fix handling of edge-cases in `no-undefined-vars`
+
+- [`bb07673`](https://github.com/primer/stylelint-config/commit/bb076732aa216fcb56e411b8dd7477efc89f7f8a) [#76](https://github.com/primer/stylelint-config/pull/76) Thanks [@BinaryMuse](https://github.com/BinaryMuse)! - Set the default verbose option for `no-scale-colors` to false
+
+## 9.3.1
+
+### Patch Changes
+
+- [`df11e2d`](https://github.com/primer/stylelint-config/commit/df11e2d912913346e0499f7eac901cdfcb83f38c) [#74](https://github.com/primer/stylelint-config/pull/74) Thanks [@BinaryMuse](https://github.com/BinaryMuse)! - Add primer/no-scale-colors to the list of exported plugins
+
+## 9.2.1
+
+### :bug: Bug fixes
+
+- Fix slow runtime by caching variable definitions in `primer/no-undefined-vars` rule
+- Fix duplicate errors in `primer/no-undefined-vars` rule
+
+## 9.2.0
+
+### :rocket: Enhancements
+
+- New `primer/no-undefined-vars` to prohibit usages of undefined CSS variables
+
+## 9.1.0
+
+### :rocket: Enhancements
+
+- The `primer/colors`, `primer/borders`, and `primer/box-shadow` rules now allow CSS color variables with the correct functional names (e.g. `var(--color-text-primary)`). #62
+
+## 9.0.0
+
+### :boom: Breaking Change
+
+- `primer/variables` is no longer supported; please use the `primer/colors`, `primer/borders`, `primer/box-shadow`, `primer/spacing`, and `primer/typography` rules instead. #50
+
+### :rocket: Enhancements
+
+- The new `primer/colors` rule enforces color variable usage in `color`, `background-color`, and `fill` properties
+- The new `primer/borders` rule enforces border variable usage in border CSS props
+- The new `primer/box-shadow` rule enforces `$box-shadow*` variables
+- The new `primer/spacing` rule enforces `$spacer-*` variables in margin and padding props
+- The new `primer/typography` rule enforces typography variable use in `font-family`, `line-height`, and `font-weight` props
+- Variable replacements for autofixing are automatically detected in variable data from Primer CSS (see: https://github.com/primer/css/pull/949) #52
+- It is now possible to define variable rules using functions that take the variables, as in:
+  ```js
+  module.exports = createVariableRule('primer/whatever', ({variables}) => {
+    /* do something with variables here */
+  })
+  ```
+- It's also now possible to provide rule _overrides_ in local stylelint configs as functions:
+  ```js
+  module.exports = {
+    extends: '@primer/stylelint-config',
+    rules: {
+      'primer/colors': [true, {
+        rules: ({variables, rules}) => {
+          /* do something with variables and/or rules here */
+          return rules
+      }]
+    }
+  })
+  ```
+- This release adds support for an optional `singular: true` flag to rule configs, which skips the parsing of individual values in the matched properties. We use this in `primer/box-shadow` to prevent multiple warnings for a single value like `box-shadow: inset 0 1px $blue` (before there would be 4 separate ones!).
+
+### :bug: Bug fixes
+
+- Use `requirePrimerFile()` when loading `dist/variables.json` so that we can access the right file when running _within_ the `@primer/css` repo.
+- Walk only declarations (`prop: value`) in rules (blocks with selectors, _not_ `@rules`), and skip linting for declarations nested in `@each`, `@for`, `@function`, and `@mixin` blocks, since those can define their own variables and we can't reliably assert their values.
+- Allow `$*-shadow` variable patterns in `primer/box-shadow` to match `$btn-active-shadow` and `$form-control-shadow`
+- Allow `color: inherit` in `primer/colors`
+- Allow `$em-spacer-*` in `padding` and `margin` properties
+- Allow (and auto-fix!) negative spacer variables in `margin` properties
+- Make `primer/colors` smarter re: `background` property shorthand values (allowing positions and image `url(*)` values)
+- Remove `100%` from allowed values for `border-radius`, and suggest `50%` instead
+- Prohibit negative spacer values in `padding` properties
+- Allow `$h000-size` for marketing 😬
+
+## 2.0.0
+
+:boom: **The following updates are breaking changes**, since code that disables the deprecated rule will now produce linting errors. Please update your `stylelint-disable` statements accordingly.
+
+- Replaced `selector-no-id: true` with `selector-max-id: 0`
+- Replaced `selector-no-type: true` with `selector-max-type: 0`
+
+The rest of the changes should not introduce new linting errors:
+
+- Updated: moved [browserslist](https://github.com/ai/browserslist) spec to `package.json`
+- Updated: using the [`no-unsupported-browser-features` plugin](https://github.com/ismay/stylelint-no-unsupported-browser-features) instead of the deprecated `no-unsupported-browser-features` rule
+- Removed: `media-feature-no-missing-punctuation`
+- Updated: replaced `rule-nested-empty-line-before` and `rule-non-nested-empty-line-before` with `rule-empty-line-before`
+
+## 1.4.0
+
+- Updated: Development dependencies are any version `*`
+- Removed: `selector-class-pattern` from config. https://github.com/primer/stylelint-config/pull/11
+
+## 1.3.0
+
+- Added: `length-zero-no-unit` to disallow zero values with units eg `0px`
+
+## 1.2.0
+
+- Removed: We don't need `scss/at-extend-no-missing-placeholder` anymore taken care of by `at-rule-blacklist`
+- Added: Adding `selector-no-type` to the rules
+
+## 1.0.0
+
+- Creating a sharable config object

package/README.md

@@ -40,6 +40,7 @@ Primer Stylelint Config extends the [stylelint-config-standard](https://github.c
 - [primer/borders](./plugins/#primerborders): Enforces the use of certain variables for border properties.
 - [primer/box-shadow](./plugins/#primerbox-shadow): Enforces the use of certain variables for `box-shadow`.
 - [primer/responsive-widths](./plugins/#primerresponsive-widths): Errors on `width` and `min-width` that is larger than the minimum browser size supported. `320px`
+- [primer/utilities](./plugins/#primerutilities): Errors when someone writes custom CSS for a declaration that has an existing primer/css/utility.
 
 ## License
 

package/index.js

@@ -9,17 +9,18 @@ module.exports = {
     'stylelint-no-unsupported-browser-features',
     'stylelint-order',
     'stylelint-scss',
-    './plugins/no-override',
-    './plugins/no-deprecated-colors',
-    './plugins/no-unused-vars',
-    './plugins/no-undefined-vars',
-    './plugins/no-scale-colors',
     './plugins/borders',
     './plugins/box-shadow',
     './plugins/colors',
+    './plugins/no-deprecated-colors',
+    './plugins/no-override',
+    './plugins/no-scale-colors',
+    './plugins/no-undefined-vars',
+    './plugins/no-unused-vars',
     './plugins/responsive-widths',
     './plugins/spacing',
-    './plugins/typography'
+    './plugins/typography',
+    './plugins/utilities'
   ],
   rules: {
     'alpha-value-notation': 'number',
@@ -69,6 +70,7 @@ module.exports = {
     'primer/responsive-widths': true,
     'primer/spacing': true,
     'primer/typography': true,
+    'primer/utilities': null,
     'scss/at-extend-no-missing-placeholder': true,
     'scss/at-rule-no-unknown': true,
     'scss/declaration-nested-properties-no-divided-groups': true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primer/stylelint-config",
-  "version": "12.4.2",
+  "version": "12.5.0-rc.d5df50d",
   "description": "Sharable stylelint config used by GitHub's CSS",
   "homepage": "http://primer.style/css/tools/linting",
   "author": "GitHub, Inc.",
@@ -39,19 +39,19 @@
     "tap-map": "^1.0.0"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "0.4.3",
+    "@changesets/changelog-github": "0.4.4",
     "@changesets/cli": "2.22.0",
     "@github/prettier-config": "0.0.4",
-    "@primer/css": "^19.0.0",
+    "@primer/css": "^20.0.0",
     "@primer/primitives": "^7.0.1",
     "dedent": "0.7.0",
-    "eslint": "8.11.0",
+    "eslint": "8.14.0",
     "eslint-plugin-github": "4.3.5",
-    "eslint-plugin-jest": "26.1.3",
+    "eslint-plugin-jest": "26.1.5",
     "eslint-plugin-prettier": "4.0.0",
     "jest": "27.5.1",
     "jest-preset-stylelint": "5.0.1",
-    "prettier": "2.6.0"
+    "prettier": "2.6.2"
   },
   "jest": {
     "preset": "jest-preset-stylelint",

package/plugins/README.md

@@ -18,6 +18,7 @@ This directory contains all of our custom stylelint plugins, each of which provi
   - [`primer/borders`](#primerborders)
   - [`primer/box-shadow`](#primerbox-shadow)
   - [`primer/responsive-widths`](#primerresponsive-widths)
+  - [`primer/utilities`](#primerutilities)
   - [Variable rules](#variable-rules)
     - [Variable rule options](#variable-rule-options)
 
@@ -212,6 +213,31 @@ This [variable rule](#variable-rules) enforces the use of `$box-shadow*` variabl
 
 This plugin checks for `width` and `min-width` declarations that use a value less than the minimum browser size. `320px`
 
+## `primer/utilities`
+
+Checks for selectors with single declarations that can be replaced with [primer/css utilities](https://primer.style/css/utilities/).
+
+```scss
+.foo {
+  color: var(--color-fg-default);
+}
+/**          ↑
+ *           FAIL: --color-fg-default can be replaced with .color-fg-default */
+
+.foo {
+  color: #custom;
+}
+/**          ↑
+ *           OK: Color value doesn't match a utility. */
+
+.foo {
+  color: var(--color-fg-default);
+  padding: 0;
+}
+/**          ↑
+ *           OK: Has more than one declaration, not considered */
+```
+
 ## Variable rules
 
 Variable rules are created using a general-purpose helper that can validate constraints for matching CSS properties and values. In general, the Primer CSS variable rules enforce two basic principles for custom CSS:

package/plugins/lib/primer-utilities.js

@@ -0,0 +1,526 @@
+// Meant as temp until we can move to primitives or css
+const colorTypes = ['accent', 'success', 'attention', 'severe', 'danger', 'open', 'closed', 'done', 'sponsors']
+
+module.exports = {
+  color: [
+    {
+      value: 'var(--color-fg-default)',
+      utilityClass: 'color-fg-default'
+    },
+    {
+      value: 'var(--color-fg-muted)',
+      utilityClass: 'color-fg-muted'
+    },
+    {
+      value: 'var(--color-fg-subtle)',
+      utilityClass: 'color-fg-subtle'
+    }
+  ].concat(
+    colorTypes.map(type => {
+      return {
+        value: `var(--color-${type}-fg)`,
+        utilityClass: `color-fg-${type}`
+      }
+    })
+  ),
+  'background-color': [
+    {
+      value: 'var(--color-canvas-default)',
+      utilityClass: 'color-bg-default'
+    },
+    {
+      value: 'var(--color-canvas-overlay)',
+      utilityClass: 'color-bg-overlay'
+    },
+    {
+      value: 'var(--color-canvas-inset)',
+      utilityClass: 'color-bg-inset'
+    },
+    {
+      value: 'var(--color-canvas-subtle)',
+      utilityClass: 'color-bg-subtle'
+    },
+    {
+      value: 'transparent',
+      utilityClass: 'color-bg-transparent'
+    }
+  ]
+    .concat(
+      colorTypes.map(type => {
+        return {
+          value: `var(--color-${type}-subtle)`,
+          utilityClass: `color-bg-${type}`
+        }
+      })
+    )
+    .concat(
+      colorTypes.map(type => {
+        return {
+          value: `var(--color-${type}-emphasis)`,
+          utilityClass: `color-bg-${type}-emphasis`
+        }
+      })
+    ),
+  'border-color': [
+    {
+      value: 'var(--color-border-default',
+      utilityClass: 'color-border-default'
+    },
+    {
+      value: 'var(--color-border-muted',
+      utilityClass: 'color-border-muted'
+    },
+    {
+      value: 'var(--color-border-subtle',
+      utilityClass: 'color-border-subtle'
+    }
+  ]
+    .concat(
+      colorTypes.map(type => {
+        return {
+          value: `var(--color-${type}-muted)`,
+          utilityClass: `color-border-${type}`
+        }
+      })
+    )
+    .concat(
+      colorTypes.map(type => {
+        return {
+          value: `var(--color-${type}-emphasis)`,
+          utilityClass: `color-border-${type}-emphasis`
+        }
+      })
+    ),
+  margin: Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `m-${i + 1}`
+    }
+  }),
+  'margin-top': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `mt-${i + 1}`
+    }
+  }),
+  'margin-right': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `mr-${i + 1}`
+    }
+  }),
+  'margin-bottom': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `mb-${i + 1}`
+    }
+  }),
+  'margin-left': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `ml-${i + 1}`
+    }
+  }),
+  padding: Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `p-${i + 1}`
+    }
+  }),
+  'padding-top': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `pt-${i + 1}`
+    }
+  }),
+  'padding-right': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `pr-${i + 1}`
+    }
+  }),
+  'padding-bottom': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `pb-${i + 1}`
+    }
+  }),
+  'padding-left': Array.from(new Array(6)).map((_, i) => {
+    return {
+      value: `$spacer-${i + 1}`,
+      utilityClass: `pl-${i + 1}`
+    }
+  }),
+  'line-height': [
+    {
+      value: '$lh-condensed-ultra',
+      utilityClass: 'lh-condensed-ultra'
+    },
+    {
+      value: '$lh-condensed',
+      utilityClass: 'lh-condensed'
+    },
+    {
+      value: '$lh-default',
+      utilityClass: 'lh-default'
+    },
+    {
+      value: '0',
+      utilityClass: 'lh-0'
+    }
+  ],
+  'text-align': [
+    {
+      value: 'left',
+      utilityClass: 'text-left'
+    },
+    {
+      value: 'right',
+      utilityClass: 'text-right'
+    },
+    {
+      value: 'center',
+      utilityClass: 'text-center'
+    }
+  ],
+  'font-style': [
+    {
+      value: 'italic',
+      utilityClass: 'text-italic'
+    }
+  ],
+  'text-transform': [
+    {
+      value: 'uppercase',
+      utilityClass: 'text-uppercase'
+    }
+  ],
+  'text-decoration': [
+    {
+      value: 'underline',
+      utilityClass: 'text-underline'
+    },
+    {
+      value: 'none',
+      utilityClass: 'no-underline'
+    }
+  ],
+  'white-space': [
+    {
+      value: 'nowrap',
+      utilityClass: 'no-wrap'
+    },
+    {
+      value: 'normal',
+      utilityClass: 'ws-normal'
+    }
+  ],
+  'word-break': [
+    {
+      value: 'break-all',
+      utilityClass: 'wb-break-all'
+    }
+  ],
+  width: [
+    {
+      value: '100%',
+      utilityClass: 'width-full'
+    },
+    {
+      value: 'auto%',
+      utilityClass: 'width-auto'
+    }
+  ],
+  overflow: [
+    {
+      value: 'visible',
+      utilityClass: 'overflow-visible'
+    },
+    {
+      value: 'hidden',
+      utilityClass: 'overflow-hidden'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'overflow-auto'
+    },
+    {
+      value: 'scroll',
+      utilityClass: 'overflow-scroll'
+    }
+  ],
+  'overflow-x': [
+    {
+      value: 'visible',
+      utilityClass: 'overflow-x-visible'
+    },
+    {
+      value: 'hidden',
+      utilityClass: 'overflow-x-hidden'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'overflow-x-auto'
+    },
+    {
+      value: 'scroll',
+      utilityClass: 'overflow-x-scroll'
+    }
+  ],
+  'overflow-y': [
+    {
+      value: 'visible',
+      utilityClass: 'overflow-y-visible'
+    },
+    {
+      value: 'hidden',
+      utilityClass: 'overflow-y-hidden'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'overflow-y-auto'
+    },
+    {
+      value: 'scroll',
+      utilityClass: 'overflow-y-scroll'
+    }
+  ],
+  height: [
+    {
+      value: '100%',
+      utilityClass: 'height-full'
+    }
+  ],
+  'max-width': [
+    {
+      value: '100%',
+      utilityClass: 'width-fit'
+    }
+  ],
+  'max-height': [
+    {
+      value: '100%',
+      utilityClass: 'height-fit'
+    }
+  ],
+  'min-width': [
+    {
+      value: '0',
+      utilityClass: 'min-width-0'
+    }
+  ],
+  float: [
+    {
+      value: 'left',
+      utilityClass: 'float-left'
+    },
+    {
+      value: 'right',
+      utilityClass: 'float-right'
+    },
+    {
+      value: 'none',
+      utilityClass: 'float-none'
+    }
+  ],
+  'list-style': [
+    {
+      value: 'none',
+      utilityClass: 'list-style-none'
+    }
+  ],
+  'user-select': [
+    {
+      value: 'none',
+      utilityClass: 'user-select-none'
+    }
+  ],
+  visibility: [
+    {
+      value: 'hidden',
+      utilityClass: 'v-hidden'
+    },
+    {
+      value: 'visible',
+      utilityClass: 'v-visible'
+    }
+  ],
+  'vertical-align': [
+    {
+      value: 'middle',
+      utilityClass: 'v-align-middle'
+    },
+    {
+      value: 'top',
+      utilityClass: 'v-align-top'
+    },
+    {
+      value: 'bottom',
+      utilityClass: 'v-align-bottom'
+    },
+    {
+      value: 'text-top',
+      utilityClass: 'v-align-text-top'
+    },
+    {
+      value: 'text-bottom',
+      utilityClass: 'v-align-text-bottom'
+    },
+    {
+      value: 'text-baseline',
+      utilityClass: 'v-align-baseline'
+    }
+  ],
+  'font-weight': [
+    {
+      value: '$font-weight-normal',
+      utilityClass: 'text-normal'
+    },
+    {
+      value: '$font-weight-bold',
+      utilityClass: 'text-bold'
+    },
+    {
+      value: '$font-weight-semibold',
+      utilityClass: 'text-semibold'
+    },
+    {
+      value: '$font-weight-light',
+      utilityClass: 'text-light'
+    }
+  ],
+  top: [
+    {
+      value: '0',
+      utilityClass: 'top-0'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'top-auto'
+    }
+  ],
+  right: [
+    {
+      value: '0',
+      utilityClass: 'right-0'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'right-auto'
+    }
+  ],
+  bottom: [
+    {
+      value: '0',
+      utilityClass: 'bottom-0'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'bottom-auto'
+    }
+  ],
+  left: [
+    {
+      value: '0',
+      utilityClass: 'left-0'
+    },
+    {
+      value: 'auto',
+      utilityClass: 'left-auto'
+    }
+  ],
+  position: [
+    {
+      value: 'static',
+      utilityClass: 'position-static'
+    },
+    {
+      value: 'relative',
+      utilityClass: 'position-relative'
+    },
+    {
+      value: 'absolute',
+      utilityClass: 'position-absolute'
+    },
+    {
+      value: 'fixed',
+      utilityClass: 'position-fixed'
+    },
+    {
+      value: 'sticky',
+      utilityClass: 'position-sticky'
+    }
+  ],
+  'box-shadow': [
+    {
+      value: 'none',
+      utilityClass: 'box-shadow-none'
+    },
+    {
+      value: 'var(--color-shadow-small)',
+      utilityClass: 'box-shadow-small'
+    },
+    {
+      value: 'var(--color-shadow-medium)',
+      utilityClass: 'box-shadow-medium'
+    },
+    {
+      value: 'var(--color-shadow-large)',
+      utilityClass: 'box-shadow-large'
+    },
+    {
+      value: 'var(--color-shadow-extra-large)',
+      utilityClass: 'box-shadow-extra-large'
+    }
+  ],
+  border: [
+    {
+      value: '$border',
+      utilityClass: 'border'
+    },
+    {
+      value: '0',
+      utilityClass: 'border-0'
+    }
+  ],
+  'border-top': [
+    {
+      value: '$border',
+      utilityClass: 'border-top'
+    },
+    {
+      value: '0',
+      utilityClass: 'border-top-0'
+    }
+  ],
+  'border-right': [
+    {
+      value: '$border',
+      utilityClass: 'border-right'
+    },
+    {
+      value: '0',
+      utilityClass: 'border-right-0'
+    }
+  ],
+  'border-bottom': [
+    {
+      value: '$border',
+      utilityClass: 'border-bottom'
+    },
+    {
+      value: '0',
+      utilityClass: 'border-bottom-0'
+    }
+  ],
+  'border-left': [
+    {
+      value: '$border',
+      utilityClass: 'border-left'
+    },
+    {
+      value: '0',
+      utilityClass: 'border-left-0'
+    }
+  ]
+}

package/plugins/utilities.js

@@ -0,0 +1,55 @@
+const stylelint = require('stylelint')
+const utilities = require('./lib/primer-utilities')
+
+const ruleName = 'primer/utilities'
+
+const messages = stylelint.utils.ruleMessages(ruleName, {
+  rejected: (selector, utilityClass) => {
+    return `Consider using the Primer utility '.${utilityClass}' instead of the selector '${selector}' in your html. https://primer.style/css/utilities`
+  }
+})
+
+// eslint-disable-next-line no-unused-vars
+module.exports = stylelint.createPlugin(ruleName, (enabled, options = {}, context) => {
+  if (!enabled) {
+    return noop
+  }
+
+  const utilityReplacement = (declaration, value) => {
+    const declarationUtilities = utilities[declaration]
+    if (declarationUtilities) {
+      return declarationUtilities.find(utility => {
+        return utility.value === value
+      })
+    }
+  }
+
+  const lintResult = (root, result) => {
+    root.walkRules(rule => {
+      if (!/^\.[\w\-_]+$/.exec(rule.selector)) {
+        return false
+      }
+      const decls = rule.nodes.filter(decl => decl.type === 'decl')
+
+      if (decls.length === 1) {
+        const replacement = utilityReplacement(decls[0].prop, decls[0].value)
+        if (replacement) {
+          stylelint.utils.report({
+            index: rule.sourceIndex,
+            message: messages.rejected(rule.selector, replacement.utilityClass),
+            node: rule,
+            result,
+            ruleName
+          })
+        }
+      }
+    })
+  }
+
+  return lintResult
+})
+
+function noop() {}
+
+module.exports.ruleName = ruleName
+module.exports.messages = messages