Stylelint Config Recess Order

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.

Package Information

• Package Name: stylelint-config-recess-order
• Package Type: npm
• Language: JavaScript (ES Modules)
• Installation: npm install --save-dev stylelint stylelint-order stylelint-config-recess-order

Core Imports

// For extending in Stylelint configuration
module.exports = {
  extends: ['stylelint-config-recess-order'],
  // ... other config
};

For custom configuration:

const propertyGroups = require('stylelint-config-recess-order/groups');

ES Modules:

import config from 'stylelint-config-recess-order';
import propertyGroups from 'stylelint-config-recess-order/groups';

Basic Usage

// stylelint.config.js
module.exports = {
  extends: ['stylelint-config-recess-order'],
  rules: {
    // Add overrides and additional rules here
  },
};

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

/* Before: Properties in any order */
div {
  background-color: slategray;
  box-sizing: border-box;
  flex: 1 1 auto;
  position: relative;
}

/* After: Properties sorted by Recess order */
div {
  position: relative;
  box-sizing: border-box;
  flex: 1 1 auto;
  background-color: slategray;
}

Architecture

Stylelint Config Recess Order is built around two main components:

• Configuration Object (index.js): A pre-configured Stylelint configuration that applies the stylelint-order plugin with Recess-based property ordering rules
• 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
• Export Strategy: Dual exports allow both simple configuration extension and advanced customization with manual rule configuration

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.

Capabilities

Default Configuration

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

/**
 * Default Stylelint configuration object with stylelint-order plugin
 * and Recess-based property ordering rules
 */
const config: StylelintConfig;

interface StylelintConfig {
  /** Array of plugin names required for this configuration */
  plugins: ['stylelint-order'];
  /** Stylelint rules configuration object */
  rules: {
    'order/properties-order': PropertyGroup[];
  };
}

Usage:

// Extend the default configuration
module.exports = {
  extends: ['stylelint-config-recess-order'],
  rules: {
    // Override or add additional rules
    'color-hex-case': 'lower',
  },
};

Property Groups

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

/**
 * Array of property groups defining Recess-based CSS property ordering
 * Each group contains related CSS properties that should be ordered together
 */
const propertyGroups: PropertyGroup[];

interface PropertyGroup {
  /** Array of CSS property names in this group */
  properties: string[];
}

Property Group Categories:

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

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

Usage:

// Custom configuration with additional options
const propertyGroups = require('stylelint-config-recess-order/groups');

module.exports = {
  extends: [], // Do not extend the config here
  rules: {
    // Configure the rule manually with custom options
    'order/properties-order': propertyGroups.map((group) => ({
      ...group,
      emptyLineBefore: 'always',
      noEmptyLineBetween: true,
    })),
  },
};

Advanced Configuration

Custom Property Ordering Options

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

const propertyGroups = require('stylelint-config-recess-order/groups');

module.exports = {
  rules: {
    'order/properties-order': propertyGroups.map((group) => ({
      ...group,
      // Add empty line before each group
      emptyLineBefore: 'always',
      // No empty lines between properties in the same group
      noEmptyLineBetween: true,
    })),
  },
};

Combining with Other Configurations

This configuration can be combined with other Stylelint configurations:

module.exports = {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-recess-order',
  ],
  rules: {
    // Additional rules or overrides
    'property-no-vendor-prefix': null,
  },
};

Dependencies

Peer Dependencies

This package requires the following peer dependencies to be installed:

• stylelint (>=16.18): The main Stylelint linting engine
• stylelint-order (>=7): Plugin that provides the order/properties-order rule

Install all dependencies:

npm install --save-dev stylelint stylelint-order stylelint-config-recess-order

Error Handling

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

Expected "box-sizing" to come before "background-color" (order/properties-order)

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

npx stylelint "**/*.css" --fix

Types

/**
 * Type definition for property group objects
 */
interface PropertyGroup {
  /** Array of CSS property names that belong to this group */
  properties: string[];
}

/**
 * Type definition for the main Stylelint configuration
 */
interface StylelintConfig {
  /** Array of plugin names required by this configuration */
  plugins: string[];
  /** Object containing Stylelint rule configurations */
  rules: {
    [ruleName: string]: any;
  };
}