@ohos-ports/stylelint-config 0.0.0-stage → 4.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +200 -2
  2. package/index.js +187 -0
  3. package/package.json +58 -5
  4. package/scss.js +8 -0
package/README.md CHANGED
@@ -1,3 +1,201 @@
1
- # Temporary Holding Version
1
+ # 10up Stylelint Config
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > At 10up, we strive to provide digital products that yield a top-notch user experience. In order to improve both our efficiency and consistency, we need to standardize what we use and how we use it. This theme scaffold allows us to share initial set up procedures to make sure all projects can get up and running as quickly as possible while closely adhering to 10up's high quality standards.
4
+
5
+ [![Support Level](https://img.shields.io/badge/support-active-green.svg)](#support-level)
6
+
7
+
8
+ ## Dependencies
9
+
10
+ 1. [Node & NPM](https://www.npmjs.com/get-npm) - 3rd party dependencies are managed through NPM, so you will need that installed globally
11
+ 2. [Stylelint](https://stylelint.io/) - as this is a config extension for Stylelint, you will need Stylelint installed in your main project in order for it to work.
12
+
13
+ ### ⚠️ Dependency Warning
14
+
15
+ If you're using `npm >= 7` you might not need to install Stylelint directly since it's stated as a `peerDependency`. If you have a version that's not equal or greater than `7`, you'll need to install Stylelint manually.
16
+
17
+ ## Installation
18
+
19
+ First, install Stylelint:
20
+
21
+ ```bash
22
+ // NPM
23
+ npm install stylelint --save-dev
24
+
25
+ // Yarn
26
+ yarn add stylelint
27
+ ```
28
+
29
+ Then install the 10up Stylelint config:
30
+
31
+ ```bash
32
+ // NPM
33
+ npm install @10up/stylelint-config --save-dev
34
+ ```
35
+
36
+ ## Usage
37
+
38
+ Add the following to your `.stylelintrc` file:
39
+
40
+ ```js
41
+ {
42
+ "extends": [
43
+ "@10up/stylelint-config"
44
+ ]
45
+ }
46
+
47
+ ```
48
+
49
+ ### SCSS:
50
+
51
+ By default, 10up Stylelint Config does not support out-the-box support for `scss` based projects. That being said, it is not difficult to add support by following the below process:
52
+
53
+ Install the `stylelint-config-standard-scss` dependency:
54
+
55
+ ```bash
56
+ // NPM
57
+ npm install stylelint-config-standard-scss --save-dev
58
+ ```
59
+
60
+ You will then need to update the plugins section of your projects `.stylelintrc`:
61
+
62
+ ```json
63
+ {
64
+ "extends": [
65
+ "stylelint-config-standard-scss",
66
+ "@10up/stylelint-config/scss"
67
+ ]
68
+ }
69
+ ```
70
+
71
+ A set of rules are located on the [packages NPM page](https://www.npmjs.com/package/stylelint-config-standard-scss) if you would like to override or customize the defaults further.
72
+
73
+ #### Selector Nested Pattern
74
+
75
+ Certain rules that apply to flavours of CSS (`postcss`, `scss`, `sass`, etc) can cause a conflict in your build pipelines. One such rule is
76
+ [Selector Nested Pattern](https://stylelint.io/user-guide/rules/selector-nested-pattern).
77
+
78
+ By default, we ensure that any nested `css` uses a prefixed `&` symbol, as required in languages like `postcss` or `postcss-preset-env`, however you will want to turn this off if using `scss`.
79
+
80
+ To get around this issue, add the following to your projects, `.stylelintrc`
81
+
82
+ ```js
83
+ {
84
+ "rules": [
85
+ "selector-nested-pattern": null,
86
+ ]
87
+ }
88
+
89
+ ```
90
+
91
+ ### Webpack Setup
92
+ Run `npm install stylelint-webpack-plugin --save-dev`. You should already have the proper loader in `postcss-loader`, but if you don't install that as well. After installing stylelint and the configuration above add the following to your Webpack config:
93
+
94
+ ```js
95
+ import StyleLintPlugin from 'stylelint-webpack-plugin';
96
+
97
+ plugins: [
98
+ new StyleLintPlugin( {
99
+ configFile: ".stylelintrc", // if your config is in a non-standard place
100
+ files: "src/**/*.css", // location of your CSS files
101
+ fix: true, // if you want to auto-fix some of the basic rules
102
+ } ),
103
+ ]
104
+ ```
105
+
106
+ Read more about these options at [stylelint-webpack-plugin](https://github.com/webpack-contrib/stylelint-webpack-plugin), [the main stylelint documentation](https://stylelint.io/) and [postcss-loader](https://github.com/postcss/postcss-loader). That should be all you need, but if there are any errors in this documentation, [please file an issue and let us know](https://github.com/10up/stylelint-config/issues/new)!
107
+
108
+ ## 10up CSS Best Practices Alignment
109
+
110
+ This configuration enforces the [10up Engineering Best Practices for CSS](https://10up.github.io/Engineering-Best-Practices/css/). Below are the key principles and how they are enforced through linting rules.
111
+
112
+ ### Low Specificity
113
+
114
+ Keeping specificity low makes CSS more maintainable and easier to override when needed.
115
+
116
+ **Enforced Rules:**
117
+ - `selector-max-specificity: "0,2,1"` - Limits selector specificity to a maximum of 0 IDs, 2 classes/attributes, and 1 element
118
+ - `selector-max-id: 0` - Disallows ID selectors for styling (IDs should be reserved for JavaScript hooks and anchors)
119
+ - `max-nesting-depth: 2` - Limits nesting to 2 levels maximum (pseudo-classes are excluded from this count)
120
+ - `no-descending-specificity: true` - Prevents specificity issues where a less specific selector comes after a more specific one
121
+
122
+ ### Avoid !important
123
+
124
+ The `!important` declaration should be avoided as it makes CSS harder to maintain and override.
125
+
126
+ **Enforced Rules:**
127
+ - `declaration-no-important: true` - Disallows the use of `!important`
128
+
129
+ Best practices reserve `!important` for truly exceptional cases, so the rule is enforced as an error by default rather than left advisory. When you hit a genuine exception -- an accessibility override such as `prefers-reduced-motion`, or fighting a third-party stylesheet you do not control -- disable it narrowly at the call site and say why:
130
+
131
+ ```css
132
+ @media (prefers-reduced-motion: reduce) {
133
+
134
+ /*
135
+ * `!important` is load-bearing: this override has to win over author
136
+ * animation declarations everywhere, so it cannot rely on the cascade.
137
+ */
138
+ *,
139
+ *::before,
140
+ *::after {
141
+ /* stylelint-disable declaration-no-important */
142
+ animation-duration: 0.001s !important;
143
+ transition-duration: 0.001s !important;
144
+ /* stylelint-enable declaration-no-important */
145
+ }
146
+ }
147
+ ```
148
+
149
+ Prefer a scoped disable over turning the rule off project-wide, so each exception stays visible and justified in review.
150
+
151
+ ### Naming Conventions
152
+
153
+ Consistent naming makes CSS more readable and maintainable. All names should use kebab-case and be semantic rather than presentational.
154
+
155
+ **Enforced Rules:**
156
+ - `selector-class-pattern` - Enforces kebab-case for class names (e.g., `.button-primary`, `.card-header`), optionally with a BEM `__element` and/or `--modifier` suffix (e.g., `.card__header`, `.card--featured`, `.card__header--compact`). BEM is permitted because 10up best practices list it as a valid methodology to adopt, and because WordPress core block classes rely on it (e.g., `.wp-block-group__inner-container`). camelCase (`.buttonPrimary`) and snake_case (`.button_primary`) are still rejected.
157
+ - `keyframes-name-pattern` - Enforces kebab-case for animation names (e.g., `@keyframes fade-in`)
158
+ - `selector-id-pattern` - Enforces kebab-case for IDs when they are used
159
+ - `custom-property-pattern` - Enforces kebab-case for CSS custom properties, with special support for WordPress preset patterns
160
+
161
+ ### Selector Quality
162
+
163
+ Writing efficient, maintainable selectors improves performance and reduces specificity issues.
164
+
165
+ **Enforced Rules:**
166
+ - `selector-no-qualifying-type: true` - Prevents qualifying class selectors with type selectors (e.g., `a.button` should be `.button`)
167
+ - `shorthand-property-no-redundant-values: true` - Ensures shorthand properties don't contain redundant values (e.g., `margin: 10px 10px` should be `margin: 10px`)
168
+
169
+ ### Additional Best Practices
170
+
171
+ The configuration also enforces:
172
+ - Consistent code formatting through stylistic rules
173
+ - Alphabetical ordering of properties for easier scanning
174
+ - Strict color value usage (colors should use custom properties)
175
+ - Proper quotes around URLs, attribute selectors, and font families
176
+
177
+ ## Overriding Rules
178
+
179
+ While these rules align with 10up best practices, there may be cases where you need to override specific rules for your project. You can do this in your project's `.stylelintrc`:
180
+
181
+ ```js
182
+ {
183
+ "extends": ["@10up/stylelint-config"],
184
+ "rules": {
185
+ // Override specific rules as needed
186
+ "selector-max-specificity": "0,3,2",
187
+ "declaration-no-important": null
188
+ }
189
+ }
190
+ ```
191
+
192
+ When overriding rules, document the reasoning in your project's CSS architecture documentation to maintain clarity for future maintainers.
193
+
194
+ ## Autofixing
195
+
196
+ Certain rules and violations can be fixed automatically using the `--fix` flag via the command line.
197
+ To ensure that Stylelint fixes what it can, you can run:
198
+
199
+ ```bash
200
+ stylelint path/to/css/file.css --fix
201
+ ```
package/index.js ADDED
@@ -0,0 +1,187 @@
1
+ module.exports = {
2
+ extends: ['stylelint-config-recommended'],
3
+ plugins: ['stylelint-stylistic', 'stylelint-declaration-strict-value', 'stylelint-order'],
4
+ rules: {
5
+ 'at-rule-disallowed-list': ['nest'],
6
+ 'at-rule-empty-line-before': [
7
+ 'always',
8
+ {
9
+ except: ['blockless-after-blockless'],
10
+ ignore: ['after-comment'],
11
+ },
12
+ ],
13
+ 'at-rule-no-unknown': [
14
+ true,
15
+ {
16
+ ignoreAtRules: ['mixin', 'define-mixin'],
17
+ },
18
+ ],
19
+ 'color-hex-length': 'short',
20
+ 'color-named': 'never',
21
+ 'comment-empty-line-before': [
22
+ 'always',
23
+ {
24
+ ignore: ['stylelint-commands'],
25
+ },
26
+ ],
27
+ 'custom-property-pattern': [
28
+ '^([a-z][a-z0-9]*)(-[a-z0-9]+)*$|^wp[-]{1,2}([a-z][a-z0-9]*)([-]{1,2}[a-z0-9]+)*$',
29
+ {
30
+ message: 'Expected custom property name to be kebab-case or wp--kebab--case',
31
+ },
32
+ ],
33
+ 'declaration-block-no-duplicate-properties': [
34
+ true,
35
+ {
36
+ ignore: ['consecutive-duplicates'],
37
+ },
38
+ ],
39
+ 'declaration-no-important': true,
40
+ 'declaration-property-unit-allowed-list': {
41
+ 'line-height': ['px'],
42
+ },
43
+ 'font-family-name-quotes': 'always-where-recommended',
44
+ 'font-weight-notation': [
45
+ 'numeric',
46
+ {
47
+ ignore: ['relative'],
48
+ },
49
+ ],
50
+ 'function-name-case': [
51
+ 'lower',
52
+ {
53
+ ignoreFunctions: ['/^DXImageTransform.Microsoft.*$/'],
54
+ },
55
+ ],
56
+ 'function-url-quotes': 'always',
57
+ 'keyframes-name-pattern': [
58
+ '^([a-z][a-z0-9]*)(-[a-z0-9]+)*$',
59
+ {
60
+ message: 'Expected keyframe name to be kebab-case (keyframes-name-pattern)',
61
+ },
62
+ ],
63
+ 'length-zero-no-unit': true,
64
+ 'max-nesting-depth': [
65
+ 2,
66
+ {
67
+ ignore: ['pseudo-classes'],
68
+ },
69
+ ],
70
+ 'no-descending-specificity': true,
71
+ 'number-max-precision': 4,
72
+ 'order/properties-alphabetical-order': true,
73
+ 'rule-empty-line-before': [
74
+ 'always',
75
+ {
76
+ ignore: ['after-comment'],
77
+ },
78
+ ],
79
+ 'scale-unlimited/declaration-strict-value': [
80
+ '/color/',
81
+ {
82
+ ignoreValues: ['currentcolor', 'inherit', 'initial', 'transparent', 'unset'],
83
+ },
84
+ ],
85
+ 'selector-attribute-quotes': 'always',
86
+ // kebab-case, optionally with a BEM `__element` and/or `--modifier`.
87
+ // BEM is permitted because 10up best practices list it as a valid
88
+ // methodology, and WordPress core block classes use it
89
+ // (e.g. `wp-block-group__inner-container`). camelCase and snake_case
90
+ // are still rejected.
91
+ 'selector-class-pattern': [
92
+ '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*(?:__[a-z0-9]+(?:-[a-z0-9]+)*)?(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?$',
93
+ {
94
+ message:
95
+ 'Expected class selector to be kebab-case or BEM block__element--modifier (selector-class-pattern)',
96
+ },
97
+ ],
98
+ 'selector-id-pattern': [
99
+ '^([a-z][a-z0-9]*)(-[a-z0-9]+)*$',
100
+ {
101
+ message:
102
+ 'Selector should use lowercase and separate words with hyphens (selector-id-pattern)',
103
+ },
104
+ ],
105
+ 'selector-max-id': 0,
106
+ 'selector-max-specificity': [
107
+ '0,2,1',
108
+ {
109
+ message: 'Selector specificity must be 0,2,1 or lower per 10up guidelines',
110
+ },
111
+ ],
112
+ 'selector-nested-pattern': '^&|\\s&$',
113
+ 'selector-no-qualifying-type': [
114
+ true,
115
+ {
116
+ ignore: ['attribute'],
117
+ },
118
+ ],
119
+ 'selector-pseudo-element-colon-notation': 'double',
120
+ 'selector-type-case': 'lower',
121
+ 'shorthand-property-no-redundant-values': true,
122
+ 'stylistic/at-rule-name-case': 'lower',
123
+ 'stylistic/at-rule-name-space-after': 'always-single-line',
124
+ 'stylistic/at-rule-semicolon-newline-after': 'always',
125
+ 'stylistic/block-closing-brace-newline-after': 'always',
126
+ 'stylistic/block-closing-brace-newline-before': 'always',
127
+ 'stylistic/block-opening-brace-newline-after': 'always',
128
+ 'stylistic/block-opening-brace-space-before': 'always',
129
+ 'stylistic/color-hex-case': 'lower',
130
+ 'stylistic/declaration-bang-space-after': 'never',
131
+ 'stylistic/declaration-bang-space-before': 'always',
132
+ 'stylistic/declaration-block-semicolon-newline-after': 'always',
133
+ 'stylistic/declaration-block-semicolon-space-before': 'never',
134
+ 'stylistic/declaration-block-trailing-semicolon': 'always',
135
+ 'stylistic/declaration-colon-newline-after': 'always-multi-line',
136
+ 'stylistic/declaration-colon-space-after': 'always-single-line',
137
+ 'stylistic/declaration-colon-space-before': 'never',
138
+ 'stylistic/function-comma-space-after': 'always',
139
+ 'stylistic/function-comma-space-before': 'never',
140
+ 'stylistic/function-max-empty-lines': 1,
141
+ 'stylistic/function-parentheses-space-inside': 'never',
142
+ 'stylistic/function-whitespace-after': 'always',
143
+ 'stylistic/indentation': 'tab',
144
+ 'stylistic/max-empty-lines': 2,
145
+ 'stylistic/max-line-length': [
146
+ 80,
147
+ {
148
+ ignore: 'non-comments',
149
+ ignorePattern: ['/(https?://[0-9,a-z]*.*)|(^description\\:.+)|(^tags\\:.+)/i'],
150
+ },
151
+ ],
152
+ 'stylistic/media-feature-colon-space-after': 'always',
153
+ 'stylistic/media-feature-colon-space-before': 'never',
154
+ 'stylistic/media-feature-range-operator-space-after': 'always',
155
+ 'stylistic/media-feature-range-operator-space-before': 'always',
156
+ 'stylistic/media-query-list-comma-newline-after': 'always-multi-line',
157
+ 'stylistic/media-query-list-comma-space-after': 'always-single-line',
158
+ 'stylistic/media-query-list-comma-space-before': 'never',
159
+ 'stylistic/no-missing-end-of-source-newline': true,
160
+ 'stylistic/number-leading-zero': 'always',
161
+ 'stylistic/number-no-trailing-zeros': true,
162
+ 'stylistic/property-case': 'lower',
163
+ 'stylistic/selector-attribute-brackets-space-inside': 'never',
164
+ 'stylistic/selector-attribute-operator-space-after': 'never',
165
+ 'stylistic/selector-attribute-operator-space-before': 'never',
166
+ 'stylistic/selector-combinator-space-after': 'always',
167
+ 'stylistic/selector-combinator-space-before': 'always',
168
+ 'stylistic/selector-list-comma-newline-after': 'always',
169
+ 'stylistic/selector-list-comma-space-before': 'never',
170
+ 'stylistic/selector-max-empty-lines': 0,
171
+ 'stylistic/selector-pseudo-class-case': 'lower',
172
+ 'stylistic/selector-pseudo-class-parentheses-space-inside': 'never',
173
+ 'stylistic/selector-pseudo-element-case': 'lower',
174
+ 'stylistic/string-quotes': 'double',
175
+ 'stylistic/unit-case': 'lower',
176
+ 'stylistic/value-list-comma-newline-after': 'always-multi-line',
177
+ 'stylistic/value-list-comma-space-after': 'always-single-line',
178
+ 'stylistic/value-list-comma-space-before': 'never',
179
+ 'value-keyword-case': [
180
+ 'lower',
181
+ {
182
+ camelCaseSvgKeywords: true,
183
+ ignoreKeywords: ['currentcolor'],
184
+ },
185
+ ],
186
+ },
187
+ };
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
- "name": "@ohos-ports/stylelint-config",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@ohos-ports/stylelint-config",
3
+ "version": "4.0.0-beta.1",
4
+ "description": "10up stylelint config for WordPress projects",
5
+ "main": "index.js",
6
+ "homepage": "https://github.com/10up/10up-toolkit/tree/develop/packages/stylelint-config#readme",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/ohos-ports/ohos-ports.git",
10
+ "directory": "ports/stylelint-config/4.0.0"
11
+ },
12
+ "publishConfig": {
13
+ "access": "public"
14
+ },
15
+ "scripts": {
16
+ "lint": "eslint .",
17
+ "test": "jest",
18
+ "test:watch": "jest --watch"
19
+ },
20
+ "keywords": [
21
+ "stylelint",
22
+ "stylelint-config",
23
+ "wordpress",
24
+ "coding-standards",
25
+ "10up"
26
+ ],
27
+ "files": [
28
+ "index.js",
29
+ "scss.js"
30
+ ],
31
+ "author": {
32
+ "name": "10up",
33
+ "email": "info@10up.com",
34
+ "url": "https://10up.com",
35
+ "role": "developer"
36
+ },
37
+ "license": "GPL-2.0-or-later",
38
+ "bugs": {
39
+ "url": "https://github.com/ohos-ports/ohos-ports/issues"
40
+ },
41
+ "engineStrict": true,
42
+ "engines": {
43
+ "node": ">=20.9.0"
44
+ },
45
+ "devDependencies": {
46
+ "@10up/eslint-config": "^5.0.0",
47
+ "jest": "^29.7.0"
48
+ },
49
+ "peerDependencies": {
50
+ "stylelint": "^15.0.0"
51
+ },
52
+ "dependencies": {
53
+ "stylelint-config-recommended": "^13.0.0",
54
+ "stylelint-config-standard-scss": "^11.0.0",
55
+ "stylelint-declaration-strict-value": "^1.9.2",
56
+ "stylelint-order": "^6.0.3",
57
+ "stylelint-stylistic": "^0.4.3"
58
+ }
59
+ }
package/scss.js ADDED
@@ -0,0 +1,8 @@
1
+ module.exports = {
2
+ extends: ['stylelint-config-standard-scss', './index.js'],
3
+ rules: {
4
+ 'at-rule-no-unknown': null,
5
+ 'import-notation': 'url',
6
+ 'scss/at-rule-no-unknown': [true, { ignoreAtRules: ['mixin', 'define-mixin'] }],
7
+ },
8
+ };