plugins

Primer stylelint plugins

This directory contains all of our custom stylelint plugins, each of which provides a single stylelint rule.

Rules

• Primer stylelint plugins
  • Rules
  • Usage
  • primer/colors
  • primer/spacing
  • primer/typography
  • primer/borders
  • primer/box-shadow
  • primer/responsive-widths
  • Variable rules
    • Variable rule options

These were intended for use with Primer CSS and GitHub projects, but you may find them useful elsewhere.

Usage

If you're using or extending @primer/stylelint-config already, then you're using all of these plugins by default. See index.js for the config defaults.

If you're not using or extending @primer/stylelint-config, you can still reference the plugins by referencing their module paths like so:

// stylelint.config.js
module.exports = {
  plugins: ['@primer/stylelint-config/plugins/colors']
}

primer/colors

This variable rule enforces the use of Primer color system variables for color and background-color CSS properties. Generally speaking, variables matching the pattern $text-* are acceptable for color (and fill), and $bg-* are acceptable for background-color. See the configuration for more info.

body {
  color: black;
}
/**           ↑
 *            FAIL: Use a variable. */

body {
  color: $gray-900;
}
/**           ↑
 *            FAIL: Use $text-gray-dark instead. */

primer/spacing

This variable rule enforces the use of Primer spacing variables in margin and padding CSS properties. See the configuration for more info.

ul {
  margin: 0 0 $spacer-3;
}
/**          ↑
 *           OK: "0" and "$spacer-*" are allowed values */

ul {
  margin: 0 0 16px;
}
/**              ↑
 *               FAIL: Use "$spacer-3" (auto-fixable!) */

primer/typography

This variable rule enforces the use of typography variables for font-size, font-weight, and line-height CSS properties. See the configuration for more info.

primer/borders

This variable rule enforces the use of border-specific variables ($border-width, $border-style, and $border-color*, and the $border shorthand) for all border CSS properties (including the border shorthand). The values 0 and none are also allowed; see the configuration for more info.

primer/box-shadow

This variable rule enforces the use of $box-shadow* variables for the box-shadow CSS property. See the configuration for more info.

primer/responsive-widths

This plugin checks for width and min-width declarations that use a value less than the minimum browser size. 320px

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:

• Use Primer variables whenever possible.
• Use functional variables ($text-gray vs. $gray-700) whenever possible.

Validations take the form of an object literal in which each key/value pair defines a set of named constraints that apply to one or more CSS properties:

{
  'background color': {
    props: 'background-color',
    // ...
  },
  'foreground color': {
    props: ['color', 'fill'],
    // ...
  }
}

The objects in each named rule may have the following keys:

• props is an array or string of glob patterns that match CSS properties. For individual properties like color, a string without any special glob characters works just fine. You can use brace expansion to match directional properties:

  'border width': {
    props: 'border{,-top,-right,-bottom,-left}-width',
    // which expands to:
    props: [
      'border-width',
      'border-top-width',
      'border-right-width',
      'border-bottom-width',
      'border-left-width'
    ]
  }

  Note: if no props are listed, the name of the rule is assumed to be the CSS property.

• values is, similar to props, an array or string of glob patterns that match individual CSS values in a single property. Property values are parsed with postcss-value-parser, so they respect parentheses, functions, and values within them. If a property has more than one value (e.g. margin: 0 auto), each one is compared against the values list to determine its validity, and a warning is generated for each invalid value.

  For example, if we fleshed out the border width rule defined above with values:

  'border width': {
    props: 'border{,-top,-right,-bottom,-left}-width',
    values: ['$border-*', '0']
  }

  Then the following SCSS checks out:

  .Box {
    border-width: 0 0 $border-width;
    /**             ↑ ↑ ↑
   *              ↑ ↑ OK!
   *              ↑ OK!
   *              OK!                */
  }

• components tells the rule that multiple values resolve to a list of ordered properties with their own, separately defined rules. This makes it possible for shorthand CSS properties like border, background, or font to "delegate" validation to a rule with more specific constraints. For example, you could enforce different types of border variables for most of the CSS border properties with:

  'border': {
    props: 'border{,-top,-right,-bottom,-left}',
    components: ['border-width', 'border-style', 'border-color']
  },
  'border width': {
    props: 'border{,-top,-right,-bottom,-left}-width',
    values: ['$border-width', '0']
  },
  'border style': {
    props: 'border{,-top,-right,-bottom,-left}-style',
    values: ['$border-style', 'none']
  },
  'border color': {
    props: 'border{,-top,-right,-bottom,-left}-color',
    values: ['$border-*', 'transparent']
  }

• replacements is an object listing property values that can safely be replaced via stylelint --fix with other variable or static values, as in the Primer CSS font-size rule:

  'font-size': {
    props: 'font-size',
    values: ['$h{0,1,2,3,4,5,6}-size', '$font-size-small'],
    replacements: {
      '40px': '$h0-size',
      '32px': '$h1-size',
      '24px': '$h2-size',
      '20px': '$h3-size',
      '16px': '$h4-size',
      '14px': '$h5-size',
      '12px': '$h6-size'
    }
  }

Variable rule options

All variable rules respect the following rule options, as in:

// stylelint.config.js
module.exports = {
  extends: '@primer/stylelint-config',
  rules: {
    'primer/colors': [true /* options here */]
    /*                ↑
     *                false disables the rule */
  }
}

• rules extends the validations for the rule, and can be used to disable specific validations, as e.g.

  rules: {
    'primer/colors': [true, {
      rules: {
        'background color': false, // disabled
        'text color': {
          // override the text color validation rules here
        }
    }]
  }

• verbose is a boolean that enables chatty console.warn() messages that may help you debug more complicated configurations.

• disableFix is a boolean that can disable auto-fixing of this rule when running stylelint --fix to auto-fix other rules.