stylelint-stylistic/stylelint-stylistic

A collection of stylistic rules for Stylelintin in a form of a plugin.

Stylelint Stylistic

An updatable collection of stylistic rules for Stylelint (in plugin form).

About and purpose

Stylelint has removed 76 rules that enforce stylistic conventions. This project returns these rules to keep styles consistent with your codeguide. In addition, new rules may be added in the future.

Installation and usage

Add @stylistic/stylelint-plugin and stylelint itself to your project:

npm add -D stylelint @stylistic/stylelint-plugin

Create the .stylelintrc config file (or open the existing one), add @stylistic/stylelint-plugin to the plugins array and the rules you need to the rules list. All rules from @stylistic/stylelint-plugin need to be namespaced with @stylistic/:

{
	"plugins": [
		"@stylistic/stylelint-plugin"
	],
	"rules": {
		// syntax rules from stylelint:
		"color-function-notation": "modern",
		"selector-max-compound-selectors": 2,

		// stylistic rules from @stylistic/stylelint-plugin:
		"@stylistic/color-hex-case": "lower",
		"@stylistic/number-leading-zero": "always",
		"@stylistic/unit-case": "lower"
	}
}

To avoid listing a lot of rules, you can use @stylistic/stylelint-config, which returns the stylistic rules removed in stylelint-config-standard and stylelint-config-recommended.

---

Please refer to Stylelint docs for detailed info on using this linter.

Need more?

ESLint deprecates stylistic rules, too. But you can continue to use them thanks to ESLint Stylistic.

Important documents

• Rule list
• Changelog
• Contributing
• License

stylelint-stylistic's Issues

Node version in package.json

What is the problem you're trying to solve?

Our project is still on node v14.

What solution would you like to see?

The latest version of this plugin requires node version >= 18.16 (link).

Stylelint itself is fine with node >=14.13 (link)

Is there any reason for higher version in this plugin? Should node version be at least the same version as stylelint?

add support to stylelint 16

What is the problem you're trying to solve?

To use the plugin.

What solution would you like to see?

Please support stylelint 16.0.0, the big one

Now the code is in ESM instead of CommonJS

Very good

Stylelint team published docs to know how to migrate with ease.

No need to keep support to commons from now on.

Style lint 16 is not allowed in your package.json. remove this restriction to

Add a rule to keep `aspect-ratio` values consistent

What is the problem you're trying to solve?

Hello,

I would like to see a new rule to control the appearance of the values of the aspect-ratio property.

Without control, the values can be variable, the following entries are all valid:

.block {
  aspect-ratio: 2 / 1;
  aspect-ratio: 2/1;
  aspect-ratio: 2;
  aspect-ratio: 2 / 1 auto;
  aspect-ratio: 2/1          auto;
  aspect-ratio: auto 2 / 1;
}

What solution would you like to see?

I'd like to have control over spaces between key values (around /) and over spaces between the parts of the value in a long form (using "auto" and the value both).

It also seems like a good idea to have a setting that disallows shortened entry like aspect-ratio: .5 because this requires keeping in mind that if there is no value for height, it defaults to 1.

It would also be good to make a setting for the position of the keyword "auto" - before the value or after.

I would create this rule.

Now I propose to discuss the name, the settings and its defaults.
I suggest we start with aspect-ratio-consistent (I don't like, but can't think of a better one) and settings in form of:

type Settings = {
  // `1 / 1` vs `1/1`
  spaceWithinRatio: 'always' | 'never',
  
  // `1 / 1 auto` vs `1 / 1        auto`
  singleSpaceBetweenValues: boolean;

  // `auto 1 / 1` vs `1 / 1 auto`
  autoKeywordPosition: 'before' | 'after'
}

Maybe the option singleSpaceBetweenValues can be enabled by the primary option 🤔
It's hard for me to imagine a scenario where someone would want to turn it off..

Problem with unknown rule errors

Describe the documentation issue

https://stackblitz.com/edit/vitejs-vite-zfhnbk?file=.stylelintrc&terminal=dev

Currently I use @stylistic/stylelint-plugin and add some rules to the config, it throws unknown rule errors. I am not sure if this is a doc issue or not, because I followed the instructions. Then I noticed that there is @stylistic/stylelint-config and with that it works correctly.

What solution would you like to see?

If this is intended behaviour maybe it should be more clear in the instructions? I've come from https://github.com/elirasza/stylelint-stylistic and my first move was to change the plugin extend and prefix the rules and that didn't work as expected.

Not Listed in NPM packages

What steps are needed to reproduce the bug?

$ npm add -D @stylistic/stylelint-plugin
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@stylistic%2fstylelint-plugin - Not found
npm ERR! 404 
npm ERR! 404  '@stylistic/stylelint-plugin@*' is not in this registry.
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

npm ERR! A complete log of this run can be found in: /Users/rgant/.npm/_logs/2023-12-18T16_11_55_957Z-debug-0.log

What Stylelint configuration is needed to reproduce the bug?

Any

How did you run Stylelint?

npm add -D @stylistic/stylelint-plugin

Which version of Stylelint are you using?

15.0.0

What did you expect to happen?

Package to be installed.

What actually happened?

404 Error

Does the bug relate to non-standard syntax?

No

Proposal to fix the bug

Push the package to the registry.

Specify tab size for `codeguide/indentation`, which affects `codeguide/max-line-length`

What is the problem you're trying to solve?

Hello.

I know it's controversial, but may be implemented.

I have indentation: tab and max-line-length: 100.

But the problem is that max-line-length counts tab as a single character. What, technically, can be right, but causes divergence between code editor and linter output:

				--background-color: color-mix(in srgb, var(--button-background-color), var(--link-color) 20%);

> stylelint styles/

If I change max-line-length to 97:

styles/index.css
 307:98  ✖  Expected line length to be no more than 97 characters  max-line-length

1 problem (1 error, 0 warnings)

What solution would you like to see?

A new option for codeguide/indentation rule. Something like tabWidth, which works only when indentation: tab.

I know: tabs are meaning to be flexible from developer to developer, etc., there are many questions to such hard-set tab size, but it's perfect for me for now (for years already, actually).

Example: RuboCop supports such thing.

https://docs.rubocop.org/rubocop/cops_layout.html#layoutindentationstyle
https://docs.rubocop.org/rubocop/cops_layout.html#layoutindentationwidth

Layout/IndentationStyle:
  EnforcedStyle: tabs
  IndentationWidth: 2
Layout/IndentationWidth:
  Width: 1

Latest update generate errors: `Cannot find module rules.js`

I have faced the missing module issue after updating to latest version 0.2.1

Error: Cannot find module './rules.js' Require stack: - /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/stylelint-codeguide/dist/index.js - /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/stylelint/lib/augmentConfig.js - /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/stylelint/lib/createStylelint.js - /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/stylelint/lib/index.js - /Users/aloksoni/.vscode/extensions/stylelint.vscode-stylelint-1.2.4/dist/start-server.js at Module._resolveFilename (node:internal/modules/cjs/loader:1010:15) at Module._load (node:internal/modules/cjs/loader:858:27) at f._load (node:electron/js2c/asar_bundle:2:13330) at Module.require (node:internal/modules/cjs/loader:1082:19) at require (node:internal/modules/cjs/helpers:102:18) at Object. (/Users/aloksoni/Proj...

here is vscode output:

[Error - 15:04:55] [language-server] Error running lint | uri: "file:///Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/src/%40core/scss/template/_variables.scss" error: {"code":"MODULE_NOT_FOUND","requireStack":["/Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected][email protected]/node_modules/stylelint-codeguide/dist/index.js","/Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/augmentConfig.js","/Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/createStylelint.js","/Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/index.js","/Users/aloksoni/.vscode/extensions/stylelint.vscode-stylelint-1.2.4/dist/start-server.js"],"name":"Error","message":"Cannot find module './rules.js'\nRequire stack:\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected][email protected]/node_modules/stylelint-codeguide/dist/index.js\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/augmentConfig.js\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/createStylelint.js\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/index.js\n- /Users/aloksoni/.vscode/extensions/stylelint.vscode-stylelint-1.2.4/dist/start-server.js","stack":"Error: Cannot find module './rules.js'\nRequire stack:\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected][email protected]/node_modules/stylelint-codeguide/dist/index.js\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/augmentConfig.js\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/createStylelint.js\n- /Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected]/node_modules/stylelint/lib/index.js\n- /Users/aloksoni/.vscode/extensions/stylelint.vscode-stylelint-1.2.4/dist/start-server.js\n at Module._resolveFilename (node:internal/modules/cjs/loader:1010:15)\n at Module._load (node:internal/modules/cjs/loader:858:27)\n at f._load (node:electron/js2c/asar_bundle:2:13330)\n at Module.require (node:internal/modules/cjs/loader:1082:19)\n at require (node:internal/modules/cjs/helpers:102:18)\n at Object. (/Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/node_modules/.pnpm/[email protected][email protected]/node_modules/stylelint-codeguide/dist/index.js:8:37)\n at Module._compile (node:internal/modules/cjs/loader:1188:14)\n at Module._extensions..js (node:internal/modules/cjs/loader:1243:10)\n at Module.load (node:internal/modules/cjs/loader:1058:32)\n at Module._load (node:internal/modules/cjs/loader:893:12)"}

Please suggest me if you know anything about the same.

`string-quotes`: fix @charset quotes

Rationale

stylelint/stylelint#2959 (comment)
stylelint/stylelint#7060

What minimal example or steps are needed to reproduce the bug?

@charset 'utf-8';

What minimal configuration is needed to reproduce the bug?

{
  "fix": true,
  "rules": {
    "string-quotes": "single" // or "double"
  }
}

How did you run Stylelint?

https://stylelint.io/demo

What did you expect to happen?

after --fix

@charset "utf-8";

What actually happened?

after --fix

@charset 'utf-8';

Options documentation

Describe the documentation issue

No documentation for rules.

What solution would you like to see?

Add documentation for all rules and options.

Add `named-grid-areas-alignment` rule

What is the problem you're trying to solve?

Hello, first of all thank you for your work :)

I've been thinking for quite some time about a rule that would format the grid-template-areas value into a table, illustrated:

Input:

.block {
  grid-template-areas:
    'column another another . a d'
    'column foo foo . e .'
    'longest-one foo foo . bar bar';
}

Output:

.block {
  grid-template-areas:
    'column       another  another  .  a    d'
    'column       foo      foo      .  e    .'
    'longest-one  foo      foo      .  bar  bar';
}

From experience, this can dramatically improve readability.

What solution would you like to see?

I could implement this rule in the scope of this package, if you're interested.
In that case, we can discuss options and edge cases here.

If you want to keep the package only for rules that were originally in Stylelint - no problem, I'll make a separate plugin for that :)
By the way, ESLint Stylistic already introduced few new rules in addition to ESLint's original stylistic rules.

What are your thoughts on this?

Rule to enforce consistent order of composite values

What is the problem you're trying to solve?

As a continuation of the idea raised here in the point 3, I suggest we discuss this in more detail here - naming and options.

I propose the following implementation plan:

1. Choose a name for the rule. I propose composite-values-order or shorthand-values-order.

2. Make a list of properties to which the rule needs to be applied. First of all these are shorthand properties like animation, transition, background and so on, but we need to decide about other values as well - for example, we can control the order of some keywords like auto in aspect-ratio property (auto 1/2 and 1/2 auto both valid). I'm sure there are others like that.

3. Make a list of tokens defining the constituents of each rule. I suggest using token names defined in MDN, for example for animation it would be ['time', 'easing-option', 'single-animation-iteration-count', '...so on'].

4. Define what default order we wish to provide without the need for additional configuration. I guess we could also focus on MDN, although for some properties personally I prefer a slightly different order... But in terms of standards, I think it's better to stick to open authoritative sources.

In the end, I envision a configuration like this:

{
  'composite-values-order': [true, {
    // only for overwriting defaults, if needed
    'aspect-ratio': ['auto', 'ratio'],
    'animation': ['time', 'easing-function', 'single-animation-iteration-count', '...']
  }]
}

---

Potential problems:

1. Properties that have some conditions (for example, in the font property, the line-height part can only come after font-size, there is a similar thing for background property, and so on).
   I don't think they can be thrown out from the configuration - we should probably come up with own compound tokens for these properties (e.g. font-size-and-line-height), but it's not very clear what to do in case of misconfiguration (lack of mandatory part) - Stylelint, as far as I know, doesn't provide a way to notify the user about invalid configuration. We'll probably have to leave that up to the users.

2. Other user misconfiguration - for example, listing not all required tokens. What to do with the remaining ones? It looks like the rule should be turned off in such cases, but how the user should know about - it's still a question.

3. Some of compound parts may have an optional order within it. Referring to MDN, linear-stop part may have a conditional order of compound parts.
   We'll probably have to add tokens that don't match CSS properties to the configuration for such scenarios.

---

So, what do you think about the name, non-shorthand properties handling, about defaults and so on?
If there are any other clarifications/opinions, I'd love to hear them. For now, I plan to go with this plan, recording progress here.
It's a long and rather difficult task, but I believe this can be done.

What solution would you like to see?

I will start working on the implementation according to the plan above after receiving feedback :)

Rule to enforce / disallow shortened value for `aspect-ratio`

What is the problem you're trying to solve?

In the discussion started here, there was a proposal to implement three new rules.

This issue for a rule that would disallow or enforce the shortened value for aspect-ratio:

aspect-ratio: 2; // shortened value, actually meaning "2 / 1"
aspect-ratio: 2 / 1; // full value

What solution would you like to see?

I would like to see this named aspect-ratio-shorthand with the only option that can be always-if-possible or never.

using never

aspect-ratio: 2; // reports and auto-fixes to "2 / 1"

using always-if-possible

aspect-ratio: 2 / 1; // reports and auto-fixes to "2"
aspect-ratio: 3 / 2; // no report

Actually there can be an option always, transforming aspect-ratio: 3 / 2 into aspect-ratio: 1.5, but in general I don't want to do this, as it seems like a really bad practice for me. But I'm ready to hear any opinions on both naming and usage.

---

To simplify my proposal - the always-if-possible option will remove the height if it is equal to 1, the never option will add a height equal to 1 if it is not specified. I believe that focusing only on integers is a good idea.

I'll listen to suggestions for naming the rule and options, then I'll make the rule :)

Add default config to export

What is the problem you're trying to solve?

Hello.

Thank you for porting these rules.

But I'd like to have some default configuration, with them enabled and configured properly.

They were in stylelint-config-standard before removing, as I know.

What solution would you like to see?

Example: stylelint-stylistic (which doesn't support Stylelint v16 yet) has such option:

https://www.npmjs.com/package/stylelint-stylistic#usage

{
  "extends": [
    "stylelint-stylistic/config"
  ]
}

https://github.com/elirasza/stylelint-stylistic/blob/main/config/index.js

node engine version is pinned to a patch version of node

What steps are needed to reproduce the bug?

Dockerfile:

FROM mcr.microsoft.com/devcontainers/typescript-node:0-18

WORKDIR /build

RUN yarn init -y && yarn add -D stylelint-codeguide

DOCKER_BUILDKIT=0 docker build -f Dockerfile .

What Stylelint configuration is needed to reproduce the bug?

none

How did you run Stylelint?

I didn't

Which version of Stylelint are you using?

latest (0.2.0)

What did you expect to happen?

stylelint-codeguide to be installed

What actually happened?

stylelint-codeguide did not install

yarn add v1.22.19
info No lockfile found.
[1/4] Resolving packages...
[2/4] Fetching packages...
error [email protected]: The engine "node" is incompatible with this module. Expected version "^18.16.1". Got "18.16.0"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command.
The command '/bin/sh -c yarn init -y && yarn add -D stylelint-codeguide' returned a non-zero code: 1

Does the bug relate to non-standard syntax?

No

Proposal to fix the bug

As not images and machines are equiped with the latest and greatest patch versions, I would like to kindly suggest to follow best common semver practice and to not pin the node engine on patch versions. (Or else to mark it as breaking.)

Fix `block-closing-brace-empty-line-before` with `after-closing-brace` false negatives for CSS Nesting

What minimal example or steps are needed to reproduce the bug?

.class {

  .class {
  }

}

What minimal configuration is needed to reproduce the bug?

"@stylistic/block-closing-brace-empty-line-before": ["never", { "except": ["after-closing-brace"]}]

How did you run Stylelint?

stylelint "**/*.css"

Which Stylelint-related dependencies are you using?

@stylistic/stylelint-plugin 2.1.0
stylelint 16.3.1

What did you expect to happen?

No error

What actually happened?

Error on last line. If you change .class to an at rule then error is gone.

Do you have a proposal to fix the bug?

No response

I'm not able to use this package with stylelint

Package version:

devDependencies:
+ stylelint-codeguide 0.2.0

 WARN  Issues with peer dependencies found
.
├─┬ stylelint-config-idiomatic-order 9.0.0
│ └─┬ stylelint-order 5.0.0
│   └── ✕ unmet peer stylelint@^14.0.0: found 15.10.0
└─┬ vite-plugin-vue-devtools 0.4.12
  └─┬ @webfansplz/vuedoc-parser 0.0.3
    └── ✕ unmet peer @types/node@^18.6.3: found 20.3.3

Here is my stylelintrc.json file

{
  "extends": [
    "stylelint-config-standard-scss",
    "stylelint-config-idiomatic-order"
  ],
  "plugins": [
    "stylelint-use-logical-spec",
    "stylelint-codeguide"
  ],
  "overrides": [
    {
      "files": [
        "**/*.scss"
      ],
      "customSyntax": "postcss-scss"
    },
    {
      "files": [
        "**/*.vue"
      ],
      "customSyntax": "postcss-html"
    }
  ],
  "rules": {
    "codeguide/max-line-length": [
      120,
      {
        "ignore": "comments"
      }
    ],
    "liberty/use-logical-spec": true,
    "selector-class-pattern": null,
    "color-function-notation": null
  }
}

And here is my stylelint out:

[Info  - 13:42:37] [language-server] Registering module | module: "auto-fix"
[Info  - 13:42:38] [language-server] Module registered | module: "auto-fix"
[Info  - 13:42:38] [language-server] Registering module | module: "code-action"
[Info  - 13:42:38] [language-server] Module registered | module: "code-action"
[Info  - 13:42:38] [language-server] Registering module | module: "completion"
[Info  - 13:42:38] [language-server] Module registered | module: "completion"
[Info  - 13:42:38] [language-server] Registering module | module: "formatter"
[Info  - 13:42:38] [language-server] Module registered | module: "formatter"
[Info  - 13:42:38] [language-server] Registering module | module: "old-stylelint-warning"
[Info  - 13:42:38] [language-server] Module registered | module: "old-stylelint-warning"
[Info  - 13:42:38] [language-server] Registering module | module: "validator"
[Info  - 13:42:38] [language-server] Module registered | module: "validator"
[Info  - 13:42:38] [language-server] Starting language server
[Info  - 13:42:38] [language-server] Registering handlers
[Info  - 13:42:38] [language-server] Handlers registered
[Info  - 13:42:38] [language-server] Language server started
/Users/aloksoni/Projects/clevision/master/vue/typescript-version/full-version/src/@core/scss/base/_vertical-nav.scss: you should use the "customSyntax" option when linting something other than CSS

No indentation and nothing works.