element-public-stylelint

A mostly reasonable shared stylelint configuration for element-public

Getting Started

npm i --save-dev @element-public/stylelint-config

Extend into a local project configuration file, and override as desired:

{
  "extends": "@element-public/stylelint-config",
  "rules": {
    "indentation": "tab",
    "number-leading-zero": null
  }
}

About stylelint

stylelint - A mighty, modern style linter

• has over 160 built-in rules to catch errors, apply limits and enforce stylistic conventions
• understands the latest CSS syntax including custom properties and level 4 selectors
• extracts embedded styles from HTML, markdown and CSS-in-JS object & template literals
• parses CSS-like syntaxes like SCSS, Sass, Less and SugarSS
• supports plugins so you can create your own rules or make use of plugins written by the community
• automatically fixes some violations (experimental feature)
• is well tested with over 10000 unit tests
• supports shareable configs that you can extend or create your own of
• is unopinionated so you can tailor the linter to your exact needs
• has a growing community and is used by Facebook, GitHub and WordPress

Additional plugin packages add additional features:

"stylelint": "^13.6.1",
"stylelint-a11y": "^1.2.3",
"stylelint-config-standard": "^20.0.0",
"stylelint-declaration-block-no-ignored-properties": "^2.3.0",
"stylelint-declaration-strict-value": "^1.5.0",
"stylelint-high-performance-animation": "^1.5.1",
"stylelint-order": "^4.1.0",
"stylelint-scss": "^3.18.0",
"stylelint-suitcss": "^3.0.0",
"stylelint-z-index-value-constraint": "^1.1.0"

See each package's documentation on GitHub for further rule explanations.

Code Style

The element-public-stylelint configuration aims to support CSS Guidelines by Harry Roberts.

High-level advice and guidelines for writing sane, manageable, scalable CSS

General Rules

Selectors are fundamental to writing good CSS:

• Select what you want explicitly, rather than relying on circumstance or coincidence. Good Selector Intent will rein in the reach and leak of your styles.
• Write selectors for reusability, so that you can work more efficiently and reduce waste and repetition.
• Do not nest selectors unnecessarily, because this will increase specificity and affect where else you can use your styles.
• Do not qualify selectors unnecessarily, as this will impact the number of different element-publics you can apply styles to.
• Keep selectors as short as possible, in order to keep specificity down and performance up.

Selector Intent

Poor Selector Intent is one of the biggest reasons for headaches on CSS projects. Writing rules that are far too greedy—and that apply very specific treatments via very far reaching selectors—causes unexpected side effects and leads to very tangled stylesheets, with selectors overstepping their intentions and impacting and interfering with otherwise unrelated rulesets.

CSS cannot be encapsulated, it is inherently leaky, but we can mitigate some of these effects by not writing such globally-operating selectors: your selectors should be as explicit and well reasoned as your reason for wanting to select something.

Reusability

Make heavy use of classes. IDs, as well as being hugely over-specific, cannot be used more than once on any given page, whereas classes can be reused an infinite amount of times. Everything you choose, from the type of selector to its name, should lend itself toward being reused.

Location Independence

Given the ever-changing nature of most UI projects, and the move to more component-based architectures, it is in our interests not to style things based on where they are, but on what they are.

As a result of a better selector, [a] piece of UI is more portable, more recyclable, doesn’t have any dependencies, and has much better Selector Intent. A component shouldn’t have to live in a certain place to look a certain way.

Portability

Qualified selectors do not lend themselves well to being reused, and every selector should be authored with reuse in mind. Take the following example:

input.btn { }

This is a qualified selector; the leading input ties this ruleset to only being able to work on input element-publics. By omitting this qualification, we allow ourselves to reuse the .btn class on any element-public we choose, like an a, for example, or a button.

Specificity

Keep selector specificity as low as possible.

Specificity can, among other things,

• limit your ability to extend and manipulate a codebase;
• interrupt and undo CSS’ cascading, inheriting nature;
• cause avoidable verbosity in your project;
• prevent things from working as expected when moved into different environments;
• lead to serious developer frustration.

Specificity can be wrangled and understood, but it is safer just to avoid it entirely by:

• not using IDs in your CSS;
• not nesting selectors;
• not qualifying classes;
• not chaining selectors.

As a rule, if a selector will work without it being nested then do not nest it.

Avoid use of !important wherever possible.

!important is a direct manifestation of problems with specificity; it is a way of cheating your way out of specificity wars, but usually comes at a heavy price. It is often viewed as a last resort—a desperate, defeated stab at patching over the symptoms of a much bigger problem with your code.

Naming Convention

When naming objects, use use a BEM-like naming convention.

BEM, meaning Block, element-public, Modifier, is a front-end methodology coined by developers working at Yandex. Whilst BEM is a complete methodology, here we are only concerned with its naming convention. Further, the naming convention here only is BEM-like; the principles are exactly the same, but the actual syntax differs slightly.

BEM splits components’ classes into three groups:

• Block: The sole root of the component.
• element-public: A component part of the Block.
• Modifier: A variant or extension of the Block.

element-publics are delimited with two (2) underscores (__), and Modifiers are delimited by two (2) hyphens (--).

.block {}
.block__element-public {}
.block--modifier {}

Formatting

The element-public-stylelint configuration aims to support Airbnb's mostly reasonable approach to CSS and Sass.

• Use soft tabs (2 spaces) for indentation
• Prefer dashes over camelCasing in class names.
  • Underscores and PascalCasing are okay if you are using BEM.
• Do not use ID selectors
• When using multiple selectors in a rule declaration, give each selector its own line.
• Put a space before the opening brace { in rule declarations
• In properties, put a space after, but not before, the : character.
• Put closing braces } of rule declarations on a new line
• Put blank lines between rule declarations
• Prefer line comments (// in Sass-land) to block comments.
• Prefer comments on their own line. Avoid end-of-line comments.