@primer/stylelint-config 12.4.2-rc.dce29d6 → 12.5.0-rc.59c3145

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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-rc.dce29d6",
+  "version": "12.5.0-rc.59c3145",
   "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