🦖 Stylelint Plugin Defensive CSS

A Stylelint plugin to enforce defensive CSS best practices.

Read more about Defensive CSS

🚀 Version 1.0.0

With the release of version 1.0.0 of the plugin, we now support Stylelint 16.

---

Getting Started

Before getting started with the plugin, you must first have Stylelint version 14.0.0 or greater installed

To get started using the plugin, it must first be installed.

npm i stylelint-plugin-defensive-css --save-dev

yarn add stylelint-plugin-defensive-css --dev

With the plugin installed, the rule(s) can be added to the project's Stylelint configuration.

{
  "plugins": ["stylelint-plugin-defensive-css"],
  "rules": {
    "plugin/use-defensive-css": [true, { "severity": "warning" }]
  }
}

Rules / Options

The plugin provides multiple rules that can be toggled on and off as needed.

1. Accidental Hover
2. Background-Repeat
3. Custom Property Fallbacks
4. Flex Wrapping
5. Scroll Chaining
6. Scrollbar Gutter
7. Vendor Prefix Grouping

---

Accidental Hover

Read more about this pattern in Defensive CSS

We use hover effects to provide an indication to the user that an element is clickable or active. That is fine for devices that have a mouse or a trackpad. However, for mobile browsing hover effects can get confusing.

Enable this rule in order to prevent unintentional hover effects on mobile devices.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "accidental-hover": true }]
  }
}

✅ Passing Examples

@media (hover: hover) {
  .btn:hover {
    color: black;
  }
}

/* Will traverse nested media queries */
@media (hover: hover) {
  @media (min-width: 1px) {
    .btn:hover {
      color: black;
    }
  }
}

/* Will traverse nested media queries */
@media (min-width: 1px) {
  @media (hover: hover) {
    @media (min-width: 100px) {
      .btn:hover {
        color: black;
      }
    }
  }
}

❌ Failing Examples

.fail-btn:hover {
  color: black;
}

@media (min-width: 1px) {
  .fail-btn:hover {
    color: black;
  }
}

Background Repeat

Read more about this pattern in Defensive CSS

Oftentimes, when using a large image as a background, we tend to forget to account for the case when the design is viewed on a large screen. That background will repeat by default.

Enable this rule in order to prevent unintentional repeating background.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "background-repeat": true }]
  }
}

✅ Passing Examples

div {
  background: url('some-image.jpg') repeat black top center;
}
div {
  background: url('some-image.jpg') black top center;
  background-repeat: no-repeat;
}

❌ Failing Examples

div {
  background: url('some-image.jpg') black top center;
}
div {
  background-image: url('some-image.jpg');
}

Custom Property Fallbacks

Read more about this pattern in Defensive CSS

CSS variables are gaining more and more usage in web design. There is a method that we can apply to use them in a way that doesn’t break the experience, in case the CSS variable value was empty for some reason.

Enable this rule in order to require fallbacks values for custom properties.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "custom-property-fallbacks": true }]
  }
}

✅ Passing Examples

div {
  color: var(--color-primary, #000);
}

❌ Failing Examples

div {
  color: var(--color-primary);
}

Option	Description
ignore	Pass an array of regular expressions and/or strings to ignore linting specific custom properties.

{
  "rules": {
    "plugin/use-defensive-css": [
      true,
      { "custom-property-fallbacks": [true, { "ignore": [/hel-/, "theme-"] }] }
    ]
  }
}

The ignore array can support regular expressions and strings. If a string is provided, it will be translated into a RegExp like new RegExp(string) before testing the custom property name.

✅ Passing Examples

div {
  /* properties with theme- are ignored */
  color: var(--theme-color-primary);

  /* properties with hel- are ignored */
  padding: var(--hel-spacing-200);
}

Flex Wrapping

Read more about this pattern in Defensive CSS

CSS flexbox is one of the most useful CSS layout features nowadays. It’s tempting to add display: flex to a wrapper and have the child items ordered next to each other. The thing is when there is not enough space, those child items won’t wrap into a new line by default. We need to either change that behavior with flex-wrap: wrap or explicitly define nowrap on the container.

Enable this rule in order to require all flex rows to have a flex-wrap value.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "flex-wrapping": true }]
  }
}

✅ Passing Examples

div {
  display: flex;
  flex-wrap: wrap;
}
div {
  display: flex;
  flex-wrap: nowrap;
}
div {
  display: flex;
  flex-direction: row-reverse;
  flex-wrap: wrap-reverse;
}
div {
  display: flex;
  flex-flow: row wrap;
}
div {
  display: flex;
  flex-flow: row-reverse nowrap;
}

❌ Failing Examples

div {
  display: flex;
}
div {
  display: flex;
  flex-direction: row;
}
div {
  display: flex;
  flex-flow: row;
}

Scroll Chaining

Read more about this pattern in Defensive CSS

Have you ever opened a modal and started scrolling, and then when you reach the end and keep scrolling, the content underneath the modal (the body element) will scroll? This is called scroll chaining.

Enable this rule in order to require all scrollable overflow properties to have an overscroll-behavior value.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "scroll-chaining": true }]
  }
}

✅ Passing Examples

div {
  overflow-x: auto;
  overscroll-behavior-x: contain;
}

div {
  overflow: hidden scroll;
  overscroll-behavior: contain;
}

div {
  overflow: hidden; /* No overscroll-behavior is needed in the case of hidden */
}

div {
  overflow-block: auto;
  overscroll-behavior: none;
}

❌ Failing Examples

div {
  overflow-x: auto;
}

div {
  overflow: hidden scroll;
}

div {
  overflow-block: auto;
}

Scrollbar Gutter

Read more about this pattern in Defensive CSS

Imagine a container with only a small amount of content with no need to scroll. The content would be aligned evenly within the boundaries of its container. Now, if that container has more content added, and a scrollbar appears, that scrollbar will cause a layout shift, forcing the content to reflow and jump. This behavior can be jarring.

To avoid layout shifting with variable content, enforce that a scrollbar-gutter property is defined for any scrollable container.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "scrollbar-gutter": true }]
  }
}

✅ Passing Examples

div {
  overflow-x: auto;
  scrollbar-gutter: auto;
}

div {
  overflow: hidden scroll;
  scrollbar-gutter: stable;
}

div {
  overflow: hidden; /* No scrollbar-gutter is needed in the case of hidden */
}

div {
  overflow-block: auto;
  scrollbar-gutter: stable both-edges;
}

❌ Failing Examples

div {
  overflow-x: auto;
}

div {
  overflow: hidden scroll;
}

div {
  overflow-block: auto;
}

Vendor Prefix Grouping

Read more about this pattern in Defensive CSS

It's not recommended to group selectors that are meant to work with different browsers. For example, styling an input's placeholder needs multiple selectors per the browser. If we group the selectors, the entire rule will be invalid, according to w3c.

Enable this rule in order to require all vendor-prefixed selectors to be split into their own rules.

{
  "rules": {
    "plugin/use-defensive-css": [true, { "vendor-prefix-grouping": true }]
  }
}

✅ Passing Examples

input::-webkit-input-placeholder {
  color: #222;
}
input::-moz-placeholder {
  color: #222;
}

❌ Failing Examples

input::-webkit-input-placeholder,
input::-moz-placeholder {
  color: #222;
}