0
# Stylelint Config Sass Guidelines
1

2
Stylelint Config Sass Guidelines is a comprehensive stylelint configuration package that enforces consistent SCSS code style based on the Sass Guidelines (sass-guidelin.es). The package provides a complete set of linting rules combining core stylelint rules, SCSS-specific rules, and stylistic formatting rules for professional SCSS development.
3

4
## Package Information
5

6
- **Package Name**: stylelint-config-sass-guidelines
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install -D stylelint postcss stylelint-config-sass-guidelines`
10

11
## Core Imports
12

13
The package exports a single configuration object that can be consumed by stylelint:
14

15
```javascript { .api }
16
// Direct import (for inspection or extension)
17
const config = require("stylelint-config-sass-guidelines");
18
```
19

20
## Basic Usage
21

22
The primary usage is through stylelint configuration files:
23

24
```json
25
{
26
  "extends": "stylelint-config-sass-guidelines"
27
}
28
```
29

30
With rule overrides:
31

32
```json
33
{
34
  "extends": "stylelint-config-sass-guidelines",
35
  "rules": {
36
    "selector-max-compound-selectors": 4,
37
    "value-no-vendor-prefix": false
38
  }
39
}
40
```
41

42
### Installation Options
43

44
Using npm:
45
```console
46
npm install -D stylelint postcss stylelint-config-sass-guidelines
47
```
48

49
Using Yarn:
50
```console
51
yarn add -D stylelint postcss stylelint-config-sass-guidelines
52
```
53

54
Using pnpm:
55
```console
56
pnpm add -D stylelint postcss stylelint-config-sass-guidelines
57
```
58

59
## Architecture
60

61
The configuration is built around three main rule categories:
62

63
- **Core Stylelint Rules**: Standard CSS/SCSS linting rules for syntax and best practices
64
- **SCSS-specific Rules**: Rules specific to SCSS syntax, variables, mixins, and functions
65
- **Stylistic Rules**: Formatting and code style rules for consistent appearance
66

67
The package integrates three key dependencies:
68
- `stylelint-scss`: Provides SCSS-specific linting capabilities
69
- `@stylistic/stylelint-plugin`: Adds stylistic formatting rules
70
- `postcss-scss`: Enables SCSS syntax parsing
71

72
## Capabilities
73

74
### Configuration Object
75

76
The main export is a complete stylelint configuration object ready for use.
77

78
```javascript { .api }
79
/**
80
 * Main stylelint configuration object
81
 * Contains plugins, custom syntax, and comprehensive rule set
82
 */
83
module.exports = {
84
  plugins: string[];
85
  customSyntax: string;
86
  rules: Record<string, any>;
87
}
88
```
89

90
The configuration object includes:
91

92
- **plugins**: Array of stylelint plugins (`["stylelint-scss", "@stylistic/stylelint-plugin"]`)
93
- **customSyntax**: SCSS syntax parser (`"postcss-scss"`)
94
- **rules**: Complete rule configuration object with 54 rules
95

96
### Core Stylelint Rules
97

98
Standard CSS/SCSS linting rules for syntax validation and best practices enforcement.
99

100
```javascript { .api }
101
interface CoreRules {
102
  // At-rule configuration
103
  "at-rule-disallowed-list": string[];           // Disallows @debug
104
  "at-rule-no-unknown": null;                    // Delegated to SCSS plugin
105
  "at-rule-no-vendor-prefix": boolean;           // Disallows vendor prefixes
106
  
107
  // Block rules
108
  "block-no-empty": boolean;                     // Disallows empty blocks
109
  
110
  // Color rules
111
  "color-hex-length": "short";                   // Forces short hex notation
112
  "color-named": "never";                        // Disallows named colors
113
  "color-no-invalid-hex": boolean;               // Validates hex colors
114
  
115
  // Declaration rules
116
  "declaration-block-single-line-max-declarations": number; // Max 1 per line
117
  "declaration-property-value-disallowed-list": Record<string, string[]>; // Disallows 'none' for border properties
118
  
119
  // Function rules
120
  "function-url-quotes": "always";               // Requires quoted URLs
121
  
122
  // General rules
123
  "length-zero-no-unit": boolean;                // No units for zero values
124
  "max-nesting-depth": [number, object];        // Limits nesting depth to 1, ignores @each, @media, @supports, @include
125
  
126
  // Property rules
127
  "property-no-unknown": boolean;                // Disallows unknown properties
128
  "property-no-vendor-prefix": boolean;          // Disallows vendor prefixes
129
  
130
  "selector-class-pattern": [string, object];   // Enforces lowercase with hyphens pattern
131
  "selector-max-compound-selectors": number;    // Limits compound selectors
132
  "selector-max-id": number;                     // Disallows ID selectors
133
  "selector-no-qualifying-type": boolean;       // Disallows type qualifiers
134
  "selector-no-vendor-prefix": boolean;         // Disallows vendor prefixes
135
  "selector-pseudo-element-colon-notation": "double";
136
  "selector-pseudo-element-no-unknown": boolean;
137
  
138
  // Value rules
139
  "shorthand-property-no-redundant-values": boolean;
140
  "value-no-vendor-prefix": boolean;            // Disallows vendor prefixes
141
  
142
  // Rule formatting
143
  "rule-empty-line-before": [string, object];  // Empty lines before rules
144
}
145
```
146

147
### SCSS-specific Rules
148

149
Rules tailored for SCSS syntax including variables, mixins, functions, and imports.
150

151
```javascript { .api }
152
interface SCSSRules {
153
  // SCSS @ rules
154
  "scss/at-extend-no-missing-placeholder": boolean;     // Requires placeholders for @extend
155
  "scss/at-function-pattern": string;                   // Function naming pattern (kebab-case)
156
  "scss/at-import-partial-extension-disallowed-list": string[]; // Disallows .scss extension in imports
157
  "scss/at-rule-no-unknown": boolean;                   // Unknown SCSS at-rules
158
  
159
  // SCSS variables
160
  "scss/dollar-variable-colon-space-after": "always";  // Space after colon
161
  "scss/dollar-variable-colon-space-before": "never";  // No space before colon
162
  "scss/dollar-variable-pattern": string;              // Variable naming pattern
163
  
164
  // SCSS imports
165
  "scss/load-no-partial-leading-underscore": boolean;  // No underscore in imports
166
  
167
  // SCSS functions
168
  "scss/no-global-function-names": boolean;            // Disallows deprecated globals
169
  
170
  // SCSS placeholders
171
  "scss/percent-placeholder-pattern": string;          // Placeholder naming pattern
172
  
173
  // SCSS selectors
174
  "scss/selector-no-redundant-nesting-selector": boolean; // No redundant & selectors
175
}
176
```
177

178
### Stylistic Rules
179

180
Formatting and code style rules for consistent visual appearance.
181

182
```javascript { .api }
183
interface StylisticRules {
184
  // Block formatting
185
  "@stylistic/block-opening-brace-space-before": "always";
186
  
187
  // Color formatting
188
  "@stylistic/color-hex-case": "lower";
189
  
190
  // Declaration formatting
191
  "@stylistic/declaration-bang-space-after": "never";
192
  "@stylistic/declaration-bang-space-before": "always";
193
  "@stylistic/declaration-block-semicolon-newline-after": "always";
194
  "@stylistic/declaration-block-semicolon-space-before": "never";
195
  "@stylistic/declaration-block-trailing-semicolon": "always";
196
  "@stylistic/declaration-colon-space-after": "always-single-line";
197
  "@stylistic/declaration-colon-space-before": "never";
198
  
199
  // Function formatting
200
  "@stylistic/function-comma-space-after": "always-single-line";
201
  "@stylistic/function-parentheses-space-inside": "never";
202
  
203
  // General formatting
204
  "@stylistic/indentation": number;                     // 2-space indentation
205
  "@stylistic/media-feature-parentheses-space-inside": "never";
206
  "@stylistic/no-missing-end-of-source-newline": boolean;
207
  
208
  // Number formatting
209
  "@stylistic/number-leading-zero": "always";
210
  "@stylistic/number-no-trailing-zeros": boolean;
211
  
212
  // Selector formatting
213
  "@stylistic/selector-list-comma-newline-after": "always";
214
  
215
  // String formatting
216
  "@stylistic/string-quotes": "single";
217
}
218
```
219

220
## Key Naming Patterns
221

222
The configuration enforces consistent naming conventions:
223

224
- **CSS Classes**: `^[a-z0-9\\-]+$` (lowercase letters, numbers, and hyphens only) with custom message "Selector should be written in lowercase with hyphens (selector-class-pattern)"
225
- **SCSS Variables**: `^[_]?[a-z]+([a-z0-9-]+[a-z0-9]+)?$` (kebab-case, optional leading underscore)
226
- **SCSS Functions**: `^[a-z]+([a-z0-9-]+[a-z0-9]+)?$` (kebab-case)
227
- **SCSS Placeholders**: `^[a-z]+([a-z0-9-]+[a-z0-9]+)?$` (kebab-case)
228

229
## Nesting and Complexity Limits
230

231
- **Max Nesting Depth**: 1 level (ignores `@each`, `@media`, `@supports`, `@include`)
232
- **Max Compound Selectors**: 3 per selector
233
- **Max Declarations per Line**: 1
234

235
## Usage Examples
236

237
### Basic Configuration
238

239
```json
240
{
241
  "extends": "stylelint-config-sass-guidelines"
242
}
243
```
244

245
### With Custom Rules
246

247
```json
248
{
249
  "extends": "stylelint-config-sass-guidelines",
250
  "rules": {
251
    "selector-max-compound-selectors": 4,
252
    "max-nesting-depth": [2, {
253
      "ignoreAtRules": ["each", "media", "supports", "include", "mixin"]
254
    }],
255
    "@stylistic/indentation": 4
256
  }
257
}
258
```
259

260
### Programmatic Usage
261

262
```javascript { .api }
263
const sassGuidelinesConfig = require("stylelint-config-sass-guidelines");
264

265
// Extend configuration
266
const customConfig = {
267
  ...sassGuidelinesConfig,
268
  rules: {
269
    ...sassGuidelinesConfig.rules,
270
    "selector-max-compound-selectors": 4
271
  }
272
};
273
```
274

275
## Dependencies
276

277
The configuration requires the following peer dependencies:
278

279
- **stylelint**: ^16.1.0 (main linting engine)
280
- **postcss**: ^8.4.21 (CSS parser)
281

282
Included dependencies:
283

284
- **stylelint-scss**: ^6.2.1 (SCSS-specific rules)
285
- **@stylistic/stylelint-plugin**: ^3.0.1 (stylistic rules)
286
- **postcss-scss**: ^4.0.9 (SCSS syntax parser)
287

288
## Node.js Compatibility
289

290
- **Minimum Node.js Version**: 18.12.0