0
# Stylelint Config Recess Order
1

2
Stylelint Config Recess Order provides a shareable Stylelint configuration that enforces CSS property ordering based on the Recess property order methodology, originally used by Bootstrap. This configuration automatically sorts CSS properties in a consistent, opinionated order that follows established conventions from the Bootstrap ecosystem.
3

4
## Package Information
5

6
- **Package Name**: stylelint-config-recess-order
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES Modules)
9
- **Installation**: `npm install --save-dev stylelint stylelint-order stylelint-config-recess-order`
10

11
## Core Imports
12

13
```javascript
14
// For extending in Stylelint configuration
15
module.exports = {
16
  extends: ['stylelint-config-recess-order'],
17
  // ... other config
18
};
19
```
20

21
For custom configuration:
22

23
```javascript
24
const propertyGroups = require('stylelint-config-recess-order/groups');
25
```
26

27
ES Modules:
28

29
```javascript
30
import config from 'stylelint-config-recess-order';
31
import propertyGroups from 'stylelint-config-recess-order/groups';
32
```
33

34
## Basic Usage
35

36
```javascript
37
// stylelint.config.js
38
module.exports = {
39
  extends: ['stylelint-config-recess-order'],
40
  rules: {
41
    // Add overrides and additional rules here
42
  },
43
};
44
```
45

46
This configuration will automatically enforce property ordering in CSS files. Properties will be sorted according to Recess methodology:
47

48
```css
49
/* Before: Properties in any order */
50
div {
51
  background-color: slategray;
52
  box-sizing: border-box;
53
  flex: 1 1 auto;
54
  position: relative;
55
}
56

57
/* After: Properties sorted by Recess order */
58
div {
59
  position: relative;
60
  box-sizing: border-box;
61
  flex: 1 1 auto;
62
  background-color: slategray;
63
}
64
```
65

66
## Architecture
67

68
Stylelint Config Recess Order is built around two main components:
69

70
- **Configuration Object** (`index.js`): A pre-configured Stylelint configuration that applies the `stylelint-order` plugin with Recess-based property ordering rules
71
- **Property Groups Array** (`groups.js`): A structured dataset containing 39 distinct property groups, each organizing related CSS properties according to their functional purpose and the Recess methodology
72
- **Export Strategy**: Dual exports allow both simple configuration extension and advanced customization with manual rule configuration
73

74
The package follows the Recess property ordering methodology, originally developed by Twitter and adopted by Bootstrap, which organizes CSS properties by their impact on layout and visual rendering.
75

76
## Capabilities
77

78
### Default Configuration
79

80
Ready-to-use Stylelint configuration with Recess-based property ordering.
81

82
```javascript { .api }
83
/**
84
 * Default Stylelint configuration object with stylelint-order plugin
85
 * and Recess-based property ordering rules
86
 */
87
const config: StylelintConfig;
88

89
interface StylelintConfig {
90
  /** Array of plugin names required for this configuration */
91
  plugins: ['stylelint-order'];
92
  /** Stylelint rules configuration object */
93
  rules: {
94
    'order/properties-order': PropertyGroup[];
95
  };
96
}
97
```
98

99
**Usage:**
100

101
```javascript
102
// Extend the default configuration
103
module.exports = {
104
  extends: ['stylelint-config-recess-order'],
105
  rules: {
106
    // Override or add additional rules
107
    'color-hex-case': 'lower',
108
  },
109
};
110
```
111

112
### Property Groups
113

114
Array of CSS property groups organized by functionality for custom configuration.
115

116
```javascript { .api }
117
/**
118
 * Array of property groups defining Recess-based CSS property ordering
119
 * Each group contains related CSS properties that should be ordered together
120
 */
121
const propertyGroups: PropertyGroup[];
122

123
interface PropertyGroup {
124
  /** Array of CSS property names in this group */
125
  properties: string[];
126
}
127
```
128

129
**Property Group Categories:**
130

131
The property groups array contains 39 distinct groups organized by CSS functionality:
132

133
1. **CSS Modules Composition** - `composes`
134
2. **Cascade and Inheritance** - `all`
135
3. **Positioned Layout** - `position`, `inset`, `top`, `right`, `bottom`, `left`, `z-index`, `float`, `clear`
136
4. **Display** - `box-sizing`, `display`, `visibility`
137
5. **Flexible Box Layout** - `flex`, `flex-grow`, `flex-shrink`, `flex-basis`, etc.
138
6. **Grid Layout** - `grid`, `grid-area`, `grid-template`, etc.
139
7. **Box Alignment** - `gap`, `align-content`, `justify-content`, etc.
140
8. **Order** - `order`
141
9. **Box Sizing** - `width`, `height`, `min-width`, `max-width`, etc.
142
10. **Box Model** - `padding`, `margin` and their logical properties
143
11. **Containment** - `contain`, `container`, `content-visibility`
144
12. **Overflow** - `overflow`, `text-overflow`, `line-clamp`, etc.
145
13. **Overscroll Behavior** - `overscroll-behavior` properties
146
14. **Fonts** - `font`, `font-family`, `font-size`, etc.
147
15. **Inline Layout** - `line-height`, `vertical-align`, etc.
148
16. **Colors** - `color`, webkit text fill properties
149
17. **Text** - `text-align`, `text-transform`, `white-space`, etc.
150
18. **Text Decoration** - `text-decoration`, `text-shadow`, etc.
151
19. **Font Loading** - `src`, `font-display`, `unicode-range`, etc.
152
20. **Basic User Interface** - `appearance`, `cursor`, `outline`, etc.
153
21. **Color Adjustment** - `color-scheme`
154
22. **Table** - `table-layout`, `border-collapse`, etc.
155
23. **Generated Content** - `content`, `quotes`
156
24. **Lists and Counters** - `list-style`, `counter-reset`, etc.
157
25. **Scroll Snap** - `scroll-snap-type`, `scroll-padding`, etc.
158
26. **Scrollbars Styling** - `scrollbar-color`, `scrollbar-width`
159
27. **Images** - `object-fit`, `image-rendering`, etc.
160
28. **Backgrounds and Borders** - `background`, `border` and all related properties
161
29. **Compositing and Blending** - `mix-blend-mode`, `isolation`, `opacity`
162
30. **Filter Effects** - `filter`, `backdrop-filter`
163
31. **Masking** - `clip`, `mask` properties
164
32. **Shapes** - `shape-outside`, `shape-margin`, etc.
165
33. **Writing Modes** - `direction`, `writing-mode`, etc.
166
34. **SVG Presentation** - `fill`, `stroke`, SVG-specific properties
167
35. **Transforms** - `transform`, `transform-origin`, etc.
168
36. **Transitions** - `transition` and related properties
169
37. **Animations** - `animation` and related properties
170
38. **Will Change** - `will-change`
171
39. **Fragmentation** - `break-before`, `widows`, `orphans`
172

173
**Usage:**
174

175
```javascript
176
// Custom configuration with additional options
177
const propertyGroups = require('stylelint-config-recess-order/groups');
178

179
module.exports = {
180
  extends: [], // Do not extend the config here
181
  rules: {
182
    // Configure the rule manually with custom options
183
    'order/properties-order': propertyGroups.map((group) => ({
184
      ...group,
185
      emptyLineBefore: 'always',
186
      noEmptyLineBetween: true,
187
    })),
188
  },
189
};
190
```
191

192
## Advanced Configuration
193

194
### Custom Property Ordering Options
195

196
The property groups can be customized with additional stylelint-order options:
197

198
```javascript
199
const propertyGroups = require('stylelint-config-recess-order/groups');
200

201
module.exports = {
202
  rules: {
203
    'order/properties-order': propertyGroups.map((group) => ({
204
      ...group,
205
      // Add empty line before each group
206
      emptyLineBefore: 'always',
207
      // No empty lines between properties in the same group
208
      noEmptyLineBetween: true,
209
    })),
210
  },
211
};
212
```
213

214
### Combining with Other Configurations
215

216
This configuration can be combined with other Stylelint configurations:
217

218
```javascript
219
module.exports = {
220
  extends: [
221
    'stylelint-config-standard',
222
    'stylelint-config-recess-order',
223
  ],
224
  rules: {
225
    // Additional rules or overrides
226
    'property-no-vendor-prefix': null,
227
  },
228
};
229
```
230

231
## Dependencies
232

233
### Peer Dependencies
234

235
This package requires the following peer dependencies to be installed:
236

237
- **stylelint** (>=16.18): The main Stylelint linting engine
238
- **stylelint-order** (>=7): Plugin that provides the `order/properties-order` rule
239

240
Install all dependencies:
241

242
```bash
243
npm install --save-dev stylelint stylelint-order stylelint-config-recess-order
244
```
245

246
## Error Handling
247

248
When properties are not in the correct order, Stylelint will report errors like:
249

250
```
251
Expected "box-sizing" to come before "background-color" (order/properties-order)
252
```
253

254
These errors can be automatically fixed using Stylelint's `--fix` option:
255

256
```bash
257
npx stylelint "**/*.css" --fix
258
```
259

260
## Types
261

262
```javascript { .api }
263
/**
264
 * Type definition for property group objects
265
 */
266
interface PropertyGroup {
267
  /** Array of CSS property names that belong to this group */
268
  properties: string[];
269
}
270

271
/**
272
 * Type definition for the main Stylelint configuration
273
 */
274
interface StylelintConfig {
275
  /** Array of plugin names required by this configuration */
276
  plugins: string[];
277
  /** Object containing Stylelint rule configurations */
278
  rules: {
279
    [ruleName: string]: any;
280
  };
281
}
282
```