0
# Stylelint Configuration
1

2
Pre-configured Stylelint setup with CSS modules, Prettier integration, and CSS-in-JS support. Provides comprehensive style linting for CSS, Less, Sass, SCSS, Stylus, and CSS-in-JS in TypeScript/JavaScript files.
3

4
## Capabilities
5

6
### Main Stylelint Configuration
7

8
Comprehensive Stylelint configuration with modern CSS support and CSS-in-JS capabilities.
9

10
```typescript { .api }
11
// Stylelint configuration object (CommonJS module.exports)
12
// Location: src/config/stylelint/index.ts
13
const stylelintConfig: {
14
  extends: string[];
15
  plugins: string[];
16
  rules: Record<string, any>;
17
  customSyntax: string;
18
  ignoreFiles: string[];
19
  overrides: Array<{
20
    files: string[];
21
    customSyntax: string;
22
  }>;
23
};
24
```
25

26
**Key Features:**
27
- **Extends**: Standard config, Prettier integration, CSS modules support
28
- **Plugins**: Declaration block validation for ignored properties
29
- **Syntax**: PostCSS Less as default syntax
30
- **CSS-in-JS**: Override for TypeScript/JavaScript files
31
- **Ignore**: Excludes node_modules automatically
32

33
**Usage:**
34

35
```javascript
36
// stylelint.config.js
37
module.exports = require("@umijs/lint/dist/config/stylelint");
38
```
39

40
## Configuration Details
41

42
### Extended Configurations
43

44
```typescript { .api }
45
const extends: [
46
  "stylelint-config-standard",
47
  "stylelint-config-prettier", 
48
  "stylelint-config-css-modules"
49
];
50
```
51

52
**Inherited Features:**
53
- **Standard**: Industry-standard CSS rules and best practices
54
- **Prettier**: Automatic formatting integration, disables conflicting style rules
55
- **CSS Modules**: Support for CSS modules naming conventions and syntax
56

57
### Custom Plugins
58

59
```typescript { .api }
60
const plugins: [
61
  "stylelint-declaration-block-no-ignored-properties"
62
];
63
```
64

65
**Plugin Features:**
66
- **Declaration Validation**: Detects CSS properties that are ignored due to other property values
67
- **Property Conflicts**: Identifies conflicting property combinations
68

69
### Syntax Support
70

71
```typescript { .api }
72
const customSyntax: "postcss-less";
73

74
const overrides: [{
75
  files: ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"];
76
  customSyntax: "@stylelint/postcss-css-in-js";
77
}];
78
```
79

80
**Supported Syntaxes:**
81
- **PostCSS Less**: Default for .css, .less, .scss, .sass, .styl files
82
- **CSS-in-JS**: Special syntax for styled-components, emotion, etc. in JS/TS files
83

84
## Rule Configuration
85

86
### Core Rules
87

88
```typescript { .api }
89
const rules: {
90
  // Specificity and ordering
91
  "no-descending-specificity": null;
92
  
93
  // URL and attribute handling  
94
  "function-url-quotes": "always";
95
  "selector-attribute-quotes": "always";
96
  
97
  // Font family validation
98
  "font-family-no-missing-generic-family-keyword": null;
99
  
100
  // Plugin rules
101
  "plugin/declaration-block-no-ignored-properties": true;
102
  
103
  // Unit validation
104
  "unit-no-unknown": [true, { ignoreUnits: ["rpx"] }];
105
  
106
  // Web components
107
  "selector-type-no-unknown": null;
108
  
109
  // CSS modules
110
  "value-keyword-case": ["lower", { ignoreProperties: ["composes"] }];
111
  
112
  // Class naming patterns
113
  "selector-class-pattern": [
114
    "^([a-z][a-z0-9]*(-[a-z0-9]+)*|[a-z][a-zA-Z0-9]+)$",
115
    {
116
      message: "Expected class selector to be kebab-case or lowerCamelCase";
117
    }
118
  ];
119
  
120
  // Color functions
121
  "color-function-notation": null;
122
  
123
  // Font family restrictions
124
  "declaration-property-value-disallowed-list": [
125
    {
126
      "font-family": "/^('|\")?PingFangSC(-(Regular|Medium|Semibold|Bold))?\\1$/"
127
    },
128
    {
129
      message: "Unexpected value for property \"font-family\", which will cause some devices to render the wrong font, please delete this \"font-family\" css rule, see also: https://github.com/umijs/umi/pull/11001"
130
    }
131
  ];
132
};
133
```
134

135
### Rule Categories
136

137
#### URL and Quote Rules
138
- **function-url-quotes**: Requires quotes around URLs in CSS functions
139
- **selector-attribute-quotes**: Requires quotes around attribute values in selectors
140

141
#### Typography Rules
142
- **font-family-no-missing-generic-family-keyword**: Disabled to allow icon fonts
143
- **Font family restrictions**: Prevents problematic PingFangSC font declarations
144

145
#### Unit and Value Rules
146
- **unit-no-unknown**: Allows rpx units (responsive pixels for mobile)
147
- **color-function-notation**: Disabled to avoid conflicts with Less math operations
148
- **value-keyword-case**: Enforces lowercase keywords except for 'composes' in CSS modules
149

150
#### Selector Rules
151
- **selector-class-pattern**: Enforces kebab-case or lowerCamelCase class names
152
- **selector-type-no-unknown**: Disabled to support web components
153
- **no-descending-specificity**: Disabled for flexibility in component styling
154

155
#### Plugin Rules
156
- **plugin/declaration-block-no-ignored-properties**: Detects ignored CSS properties
157

158
## File Support
159

160
### Supported File Extensions
161

162
```typescript { .api }
163
const supportedFiles: [
164
  "**/*.css",   // CSS files
165
  "**/*.less",  // Less files  
166
  "**/*.scss",  // SCSS files
167
  "**/*.sass",  // Sass files
168
  "**/*.styl"   // Stylus files
169
];
170
```
171

172
### CSS-in-JS Support
173

174
```typescript { .api }
175
const cssInJsFiles: [
176
  "**/*.js",    // JavaScript files with CSS-in-JS
177
  "**/*.jsx",   // JSX files with CSS-in-JS
178
  "**/*.ts",    // TypeScript files with CSS-in-JS  
179
  "**/*.tsx"    // TSX files with CSS-in-JS
180
];
181
```
182

183
**CSS-in-JS Features:**
184
- Styled-components support
185
- Emotion CSS support
186
- Template literal CSS parsing
187
- JSX style prop validation
188

189
## Usage Examples
190

191
### Basic CSS Linting
192

193
```bash
194
# Lint CSS files
195
stylelint "src/**/*.{css,less,scss}"
196

197
# Lint with auto-fix
198
stylelint "src/**/*.{css,less,scss}" --fix
199
```
200

201
### CSS-in-JS Linting
202

203
```bash
204
# Lint CSS-in-JS in TypeScript files
205
stylelint "src/**/*.{ts,tsx}"
206

207
# Lint all style-related files
208
stylelint "src/**/*.{css,less,scss,ts,tsx}"
209
```
210

211
### Configuration Override
212

213
```javascript
214
// stylelint.config.js
215
const baseConfig = require("@umijs/lint/dist/config/stylelint");
216

217
module.exports = {
218
  ...baseConfig,
219
  rules: {
220
    ...baseConfig.rules,
221
    "color-hex-case": "upper",
222
    "declaration-block-trailing-semicolon": "always"
223
  }
224
};
225
```
226

227
## CSS Modules Integration
228

229
### Class Naming Convention
230

231
```css
232
/* Valid class names */
233
.my-component { }        /* kebab-case */
234
.myComponent { }         /* lowerCamelCase */
235
.component-item { }      /* kebab-case with hyphens */
236

237
/* Invalid class names */
238
.MyComponent { }         /* PascalCase - not allowed */
239
.my_component { }        /* snake_case - not allowed */
240
```
241

242
### Composes Property
243

244
```css
245
/* CSS Modules composition */
246
.button {
247
  composes: base-button from './base.css';
248
  background: blue;
249
}
250
```
251

252
**Special Handling:**
253
- `composes` keyword is case-insensitive (exception to lowercase rule)
254
- Supports CSS Modules composition syntax
255
- Validates composed class references
256

257
## Less Integration
258

259
### Math Operations
260

261
```less
262
// Less math operations are supported
263
.container {
264
  width: calc(100% - 20px);  // Standard CSS calc
265
  height: 100px * 2;         // Less multiplication
266
  margin: 10px / 2;          // Less division
267
}
268
```
269

270
**Configuration:**
271
- `color-function-notation` is disabled to prevent conflicts with Less math
272
- PostCSS Less syntax handles Less-specific features
273
- Supports Less variables, mixins, and functions
274

275
## Error Handling
276

277
### Common Configuration Issues
278

279
**Missing Dependencies:**
280
```bash
281
# Ensure required packages are installed
282
npm install stylelint postcss
283
```
284

285
**Syntax Errors:**
286
- PostCSS Less handles most syntax variations
287
- CSS-in-JS parser handles template literals and JSX
288

289
**File Pattern Issues:**
290
- Use glob patterns for file matching
291
- Ensure file extensions match override patterns
292

293
### Ignoring Files
294

295
```javascript
296
// stylelint.config.js
297
module.exports = {
298
  ...require("@umijs/lint/dist/config/stylelint"),
299
  ignoreFiles: [
300
    "node_modules/**/*",
301
    "dist/**/*",
302
    "build/**/*"
303
  ]
304
};
305
```
306

307
## Advanced Features
308

309
### Custom Property Validation
310

311
```css
312
/* Custom properties (CSS variables) */
313
:root {
314
  --primary-color: #007bff;
315
  --font-size-base: 16px;
316
}
317

318
.component {
319
  color: var(--primary-color);
320
  font-size: var(--font-size-base);
321
}
322
```
323

324
### Web Components Support
325

326
```css
327
/* Custom elements are allowed */
328
my-custom-element {
329
  display: block;
330
  padding: 1rem;
331
}
332

333
app-header,
334
app-footer {
335
  position: relative;
336
}
337
```
338

339
### Responsive Units
340

341
```css
342
/* rpx units are supported (responsive pixels) */
343
.mobile-component {
344
  width: 750rpx;    /* Allowed */
345
  height: 200rpx;   /* Allowed */
346
  font-size: 32rpx; /* Allowed */
347
}
348
```