primer/stylelint-config

Sharable stylelint config used by GitHub's CSS

Primer Stylelint Config

A sharable stylelint config object that enforces GitHub's CSS rules

Install

$ npm install --save --dev @primer/stylelint-config

Usage

Within your stylelint config object You can extend this configuration. This will serve as a base for your config, then you can make overrides in your own config object:

{
  "extends": ["@primer/stylelint-config"],
  "rules": { }
}

Documentation

Primer Stylelint Config extends the stylelint-config-standard configuration supplied by Stylelint, and makes modifications in /index.js.

Plugins

• stylelint-order: Order-related linting rules for stylelint. Properties must be sorted according to this list.
• stylelint-scss: A collection of SCSS specific linting rules for stylelint
  • scss/selector-no-redundant-nesting-selector: Disallow redundant nesting selectors (&).
• primer/no-override: Prohibits custom styles that target Primer CSS selectors.
• primer/no-unused-vars: Warns about SCSS variables that are declared by not used in your local files.
• primer/no-undefined-vars: Prohibits usage of undefined CSS variables.
• primer/no-scale-colors: Prohibits the use of non-functional scale CSS variables
• primer/colors: Enforces the use of certain color variables.
• primer/spacing: Enforces the use of spacing variables for margin and padding.
• primer/typography: Enforces the use of typography variables for certain CSS properties.
• primer/borders: Enforces the use of certain variables for border properties.
• primer/box-shadow: Enforces the use of certain variables for box-shadow.
• primer/responsive-widths: Errors on width and min-width that is larger than the minimum browser size supported. 320px
• primer/utilities: Errors when someone writes custom CSS for a declaration that has an existing primer/css/utility.

License

MIT © GitHub

stylelint-config's Issues

Use jest-preset-stylelint?

Currently we're using some custom expect matchers that I wrote in our tests, but today I discovered stylelint/jest-preset-stylelint, which might offer a more concise API? 🤷‍♀

Don't allow undefined CSS variables

Issue originally raised by @BinaryMuse in #62 (comment)

Problem

To enable color modes in Primer CSS, we are transitioning from SCSS variables for colors to CSS variables. Using CSS variables means that the SCSS compiler will no longer fail if someone misspells a variable name.

Do this

• Update stylelint-config-primer to flag usages of CSS color variables that don't exist in Primer Primitives

Autofix for Node API

Hi.
I use Node Api.
I use the design from the documentation.

stylelint
  .lint({
    code: "a { color: pink; }",
    config: myConfig,
    formatter: "verbose"
  })
  .then(function () {
    /* .. */
  });

Is there a possibility that the corrected version of the file would also be the result of the execution of the verification code. ?

Cannot find module '@primer/css/dist/meta.json'

I get an error on execute the command stylelint 'src/**/*.scss' --syntax scss

Error: Cannot find module '@primer/css/dist/meta.json'

Separate properties groups with empty lines

Hi!

Day after day, after specification, we get new css properties.

Please, consider to add empty lines between groups of related properties on the orders rule to make the file easier to read.

Old css linters had this. We can use one of them as a starting point.

What do you think?

Thank you for your attention.

npm audit low-severity warning

I think it's actually not a vulnerability but I don't like this warning. Solution is about to upgrade stylelint to proper version. Seems like this PR refers to this problem: stylelint/stylelint#3660

Break up primer/variables into separate rules

Right now the configuration object for the primer/variables rule is really big and unwieldy. Its monolithic nature also makes refactoring via stylelint --fix tricky, because not only do you have to drill your stylelint config's rules down to only primer/variables, but if you want to focus on one type of rule (margins and padding vs. borders, for instance), you have to disable all the other variable rules with something crazy like this.

So, I think there should be different stylelint-level rules for each "type" of variable or value. For instance:

• primer/fg-color deals with text color and SVG fill properties
• primer/bg-color deals with background-color (and the color component of background)
• primer/borders deals with border-width, border-style, border-color, and maybe outline?
• primer/whitespace deals with margin, padding, and spacer variables more generally
• primer/box-shadow deals with (you guessed it) box-shadow
• primer/typography deals with font-size, font-weight, line-height, and the respective font components

What do you think, @primer/ds-core ?

Require newline after comma

I think this style guide should require a newline after commas in value lists. For example,
This would be flagged:

.dp-4 {
  box-shadow:  0 4px 5px 0 rgba(0, 0, 0, 0.14), 0 1px 10px 0 rgba(0, 0, 0, 0.12), 0 2px 4px -1px rgba(0, 0, 0, 0.2);
}

But this wouldn't:

.dp-4 {
  box-shadow:
    0 4px 5px 0 rgba(0, 0, 0, 0.14),
    0 1px 10px 0 rgba(0, 0, 0, 0.12),
    0 2px 4px -1px rgba(0, 0, 0, 0.2);
}

This can be done by putting this in your stylelint config:

"rules": {
   "value-list-comma-newline-after": "always"
 },

I figure that if you do this for selectors, you should do this for value lists.

stylelint --fix is not working when primer rules is enabled

If I enable primer/no-unused-vars, I cannot use --fix feature of Stylelint.

If I just disable it, like "primer/no-unused-vars": false or remove this line, --fix is working again.

Require :focus styles to accompany :hover

This is an accessibility issue. There have been some discussions about a pseudo-selector that combines the two, but we should at least be warning folks if they add :hover styles without also adding :focus.

/cc @primer/ds-core

Empty line between blocks

Hi!

May you consider adding empty lines between line blocks? The list of properties is [sooooooooooo] long.

I can update the config and submit a pull request, if you agree.

Thank you!

Upgrade stylelint-scss to support stylelint v10

Shouldn't `all` be the first rule?

Being all a reset, shouldn't it be the first rule?

Don't allow SCSS color variables

Problem

To enable color modes in Primer CSS, we are transitioning from SCSS variables for colors to CSS variables. Our stylelint config, however, still allows people to use SCSS color variables.

Do this

• Update stylelint-config-primer to flag usages of SCSS color variables as errors and recommend an appropriate CSS variable alternative if one exists

Add stylelint-use-nesting

This rule enforces use of nesting, and can take exceptions if there's anywhere that we absolutely don't want it.

Make this easier to find

When I go to https://github.com/styleguide and click on Primer (HTML and CSS), I get redirected to https://primer.style/. When I click on Style Guide, I get what I wasn't looking for. Why is this so hard to find?

Add primer/deprecations rule

This would use the deprecations data published with @primer/css as of 12.7.0 to determine if anyone is styling deprecated selectors (see primer/css#883 for more info).

I'm honestly not sure how useful this would be, but it might clue us in to major version upgrade issues without having to search bigger codebases for all of the deprecated class names.

Add rule for checking for use of transparent in liner gradient

Per @simurai in https://github.com/github/github/pull/169601:

It seems that if a gradient uses transparent, Safari renders the "in-between" with a dark-ish color. The fix is to use rgba(255, 255, 255, 0) which is "transparent" too, but tells Safari what color to use for the interpolation. More details here.

It'd be nice to be able to lint against this so we don't run into this in the future.

@primer/css canary releases don't satisfy peer dependency

We currently have @primer/css listed as a peer dependency with the >=12 version specifier, which causes npm to bail when this package is installed alongside canary releases, which are always 0.0.0-{sha}. The version specifier is too specific because the first release of @primer/css (as opposed to primer) was 12.0.0, so this can be loosened to *.

Stylelint improvements for CSS modules

Just a list of some little improvements

• Default config to CSS first, treat SCSS as overrides
• Support for CSS in JS (React)
• Upgrade stylelint to next major

Rules

• Better support for CSS variables
• Triage existing rules
• Better mapping for color CSS variables to properties

Tasks

• Rewite primer-borders
• Rewrite box-shadows
• Rewrite colors
• Delete no-deprecated-colors
• Add no deprecated variables
• Delete no-experimental variables
• Delete no-overrides
• Delete no-scale-colors
• Rewrite no-undefined-vars (research)
• Delete no-unused-vars
• Leave responsive-vars
• Rewrite primer-spacing
• Rewrite typography
• Rewrite utilities

Unable to get variables.json from @primer/css. Replacements will need to be specified manually

for the command npx stylelint "src/**/*.css", over the:

package.json file

{
  "name": "demo",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^4.2.4",
    "@testing-library/react": "^9.5.0",
    "@testing-library/user-event": "^7.2.1",
    "react": "^16.13.1",
    "react-dom": "^16.13.1",
    "react-router-dom": "^5.2.0",
    "react-scripts": "3.4.1"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "eslint": "npx eslint src/**/*.{js,jsx}",
    "eslint:fix": "npx eslint src/**/*.{js,jsx} --fix"
  },
  "eslintConfig": {
    "extends": "react-app"
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "eslint": "^6.8.0",
    "eslint-config-airbnb": "^18.1.0",
    "eslint-plugin-import": "^2.20.2",
    "eslint-plugin-jsx-a11y": "^6.2.3",
    "eslint-plugin-react": "^7.20.0",
    "eslint-plugin-react-hooks": "^4.0.4",
    "stylelint": "^13.5.0",
    "stylelint-config-primer": "^9.0.0",
    "stylelint-config-standard": "^20.0.0"
  }
}

and the .stylelintrc.yml file

files:
  include:
  - 'src/index.css'
  - 'src/**/*.css'
  - 'public/**/*.css'
  ignore:
  - './src/assets/**'
  - './node_modules/**'
  - './docs/**'
  - './trash/**'

extends:
  - stylelint-config-primer

I get this on my console

Unable to get variables.json from @primer/css. Replacements will need to be specified manually.
Unable to get variables.json from @primer/css. Replacements will need to be specified manually.
Unable to get variables.json from @primer/css. Replacements will need to be specified manually.
Unable to get variables.json from @primer/css. Replacements will need to be specified manually.
Unable to get variables.json from @primer/css. Replacements will need to be specified manually.
Error: Cannot find module '@primer/css/dist/meta.json'
Require stack:

• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint-config-primer/plugins/lib/primer.js
• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint-config-primer/plugins/no-override.js
• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/lib/augmentConfig.js
• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/lib/createStylelint.js
• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/lib/printConfig.js
• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/lib/cli.js
• /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/bin/stylelint.js
  at Function.Module._resolveFilename (internal/modules/cjs/loader.js:793:17)
  at Function.Module._load (internal/modules/cjs/loader.js:686:27)
  at Module.require (internal/modules/cjs/loader.js:848:19)
  at require (/home/davincif/Documentos/projects/lab/react/demo/node_modules/v8-compile-cache/v8-compile-cache.js:161:20)
  at requirePrimerFile (/home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint-config-primer/plugins/lib/primer.js:23:10)
  at /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint-config-primer/plugins/no-override.js:25:22
  at /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/lib/lintSource.js:209:6
  at Array.map ()
  at /home/davincif/Documentos/projects/lab/react/demo/node_modules/stylelint/lib/lintSource.js:208:18
  at Array.forEach ()

Am I doing something crazy or this is a bug?