Skip to content

jonpearse/grouped_property_scss_linter

Repository files navigation

Grouped Property Linter for SCSS-Lint

This is a plugin linter for SCSS-Lint that provides a saner alternative to the built-in PropertySortOrder linter.

Instead of requiring properties to be arranged in a strict order, it instead allows groups of properties (eg: top, right, bottom & left) to be defined, and then lints the order of the groups in your SASS.
As long as properties are grouped correctly, the order of individual properties is unimportant.

Examples

Using the default configuration:

Bad

.selector {
  padding: .625rem;

  text-decoration: underline;
  font-size: 1rem;
  line-height: 1.3;
  font-weight: bold;
  color: rgba(20, 20, 20, .8);

  display: inline-block;
  background: #F00;
}

Good

.selector {
  display: inline-block;
  padding: .625rem;

  color: rgba(20, 20, 20, .8);
  background: #F00;

  font-size: 1rem;
  line-height: 1.3em;
  font-weight: bold;
  text-decoration: underline;
}

Because the order of individual properties within a group is ignored, neither of the selectors below would generate a warning.

.selector-one {
  display: block;

  height: 10em;
  width:  90%;
}

.selector-two {
  display: block;

  width:  90%;
  height: 10em;
}

Usage

In order to use this linter, you’ll need to modify both your Gemfile and scss-lint configuration file (typically .scss-lint).

Gemfile

gem 'grouped_property_scss_linter'

SCSS-Lint configuration file

You will need to add grouped_property_scss_linter to the plugin_gems variable:

plugin_gems: ['grouped_property_scss_linter']

Configuration

When included, this linter is enabled by default, and enforces a modified version of SMACSS’s categories

The configuration may be altered in the same way as other linters, by adding a section to your SCSS-Lint configuration file.

linters:
  GroupedPropertyOrder:
    enabled: true
    defaults:
      space_around: true
      max_no_space: 3
    style: smacss
    groups:

Options

enabled (boolean)
switches the module on and off (default: on)
defaults (hash)
default linting settings that are applied to all groups (can be overridden per-group)
style (string, optional)
the name of a preconfigured style (see below, defaults to grouped-smacss)
css_variables_first (boolean, optional)
whether or not require CSS variables (custom properties) are defined first (default: true)
groups (hash, optional)
a hash of configured groups. Note that specifying anything here will override the style option
extended_hinting (boolean, optional)
enables additional group information in hinting output (default false)

Default options

space_around (boolean)
whether to require space around individual groups (default: true)
max_no_space (int)
the maximum number of properties that can be specified in a group before space is required around it (default: 3, ignored if space_around is false)

Predefined styles

There a number of property orders/styles supplied with the gem. These are:

smacss
an implementation of SMACSS
grouped-smacss (default)
a tweaked version of SMACSS with slightly more granular grouping
concentric
an implementation of Concentric CSS
personal
my personal ordering, just cuz…

Specifying your own configuration

Groups are specified as a YAML hash, in the order in which they should appear in your SASS. Each group must have a properties member, containing an array of properties that may appear in this group.

groups:
  tables:
    properties:
      - table-layout
      - border-collapse
      - empty-cells

Specifies a group called tables, which may contain table-layout, border-collapse and empty-cells properties.

Wildcard properties

In cases where a number of properties may have the same prefix, wildcard properties may used instead.
Thus, the following group definitions are equivalent.

groups:
  text:
    properties:
      - font
      - font-size
      - font-family
      - font-style
  text_two:
    properties:
      - font*

Naturally, you might want to use this functionality carefully…

Overriding defaults

In some cases, you may wish to override the default linting options. This can be done by adding the appropriate option to the group hash:

groups:
  tables:
    max_no_space: 1
    properties:
      - table-layout
      - border-collapse
      - empty-cells

This defines a tables group as earlier, but requires a space around it at all times.

Why?

I’ve written a blog post about this, but the short version is that I really don’t get on with SCSS-Lint’s default PropertySortOrder linter =)

Version History

1.2.0 (May 21st, 2018)

  • [FIX] CSS variables no longer cause an infinite loop (fixes issue #1)
  • moved stuff around in my ‘personal’ preset

1.1.3 (March 18th, 2017)

  • eventually pushing this up to RubyGems

1.1.1 (July 15th, 2016)

  • fixing dumb typoes in the readme

1.1.0 (July 15th, 2016)

  • improved hint messages to be somewhat more useful to the average developer

1.0.0 (June 12th, 2016)

  • initial release

Mandatory sales pitch

When I’m not hacking at random things, I’m a freelance web developer specialising in all things front-end, based in the beautiful city of Cardiff, UK.
I’m usually kept fairly busy with project work, but I’m always on the lookout for new people to do cool stuff with. Drop me a line – I’d love to hear from you!

About

Group-based linting plugin for SCSS-Lint

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages