Skip to content

theKashey/stylelint-semantic-groups

Repository files navigation

stylelint-semantic-groups

Opinionated group based SCSS property ordering for better maintainability and perception.

📖 Theory behind: Harry Potter and the Order of CSS


Usage

  • install required packages
yarn add stylelint-order stylelint-semantic-groups
  • set configuration

Recommended configuration

// .stylelintrc.js
const { propertyOrdering, selectorOrdering } = require('stylelint-semantic-groups');

module.exports = {
  plugins: ['stylelint-order'],
  rules: {
    'order/order': selectorOrdering, // to fine-tune configuration use selectorOrderFactory
    'order/properties-order': propertyOrdering,
  },
};

Minimal configuration

// .stylelintrc.js
const { propertyOrdering } = require('stylelint-semantic-groups');

module.exports = {
  plugins: ['stylelint-order'],
  rules: {
    /* optional by recommended */
    'order/order': [
      'custom-properties',
      'dollar-variables',
      'declarations',
      'at-rules', // <-- important, `@media` should go before `&:pseudo`
      'rules',
    ],
    /* the actual usage of this package */
    'order/properties-order': propertyOrdering,
  },
};

Stylelint config that sorts related property declarations by grouping together following the order:

  • (optional) SCSS/CSS variables, handled by order/order
  • Layout Positioning - Element bound properties (in terms of BEM) such as grid-area. Note: in the current implementation it is mostly about grids and grids only.
  • Positioning
  • Box Model
  • Typography
  • Visual
  • Misc
  • Animation
  • (optional) at-rules, handled by order/order
  • (optional) nested rules, handled by order/order
.declaration-order {
  --color: #fff;

  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 10;

  /* Box Model */ /* white space between groups is ENFORCED */
  display: block;
  float: right;
  width: 100px;
  height: 100px;
  margin: 10px;
  padding: 10px;

  /* Typography */
  color: #888;
  font: normal 16px Helvetica, sans-serif;
  line-height: 1.3;
  text-align: center;

  /* Visual */
  background-color: #eee;
  border: 1px solid #888;
  border-radius: 4px;
  opacity: 1;

  /* Animation */
  transition: all 1s;

  /* Misc */
  user-select: none;
}

See also

Licence

MIT