CSS Linting with Stylelint: Catching Syntax Errors

CSS linting with Stylelint is an essential quality assurance process that analyzes stylesheets to detect syntax errors, enforce consistent coding standards, and eliminate invalid rules before code reaches production. This article explains what Stylelint is, how it operates within modern web development workflows, and the specific categories of syntax mistakes and invalid CSS declarations it catches to prevent silent rendering failures in browsers.

What is Stylelint?

Stylelint is a robust, open-source linter designed specifically for modern CSS and CSS preprocessors such as SCSS, Less, and SugarSS, as well as CSS-in-JS implementations. Similar to how ESLint functions for JavaScript, Stylelint performs static analysis on your stylesheets without executing them. It parses your code into an Abstract Syntax Tree (AST), checks it against configured rules, and alerts you to typos, deprecated features, structural mistakes, and styling violations.

Browsers are designed to be forgiving with CSS; when they encounter an unknown rule or broken syntax, they silently ignore it rather than throwing a fatal error. This permissive behavior often leads to hard-to-diagnose layout bugs. Stylelint solves this issue by exposing these errors directly inside code editors and Continuous Integration (CI) pipelines.

Syntax Errors Caught by Stylelint

Stylelint detects a wide array of syntax problems, ranging from simple typographic mistakes to complex structural flaws.

1. Unknown or Misspelled CSS Properties

Stylelint validates every property name against official web standards. If a developer mistypes a property name, browsers discard the line completely.

  • Caught Error: Writing colr: #333; or pading-top: 10px; instead of color or padding-top.

2. Invalid Units and Dimensions

CSS values frequently require valid units of measurement. Stylelint checks whether the units attached to numerical values are recognized by current CSS specifications.

  • Caught Error: Specifying width: 200pix;, margin: 12pxx;, or font-size: 1.2rems;.

3. Unknown Selectors, Pseudo-Classes, and Pseudo-Elements

Stylelint verifies that all pseudo-classes and pseudo-elements conform to valid web specifications.

  • Caught Error: Writing :hoverr, :nth-child(foo), or ::afterr. It also catches malformed attribute selectors, such as missing brackets or invalid operators.

4. Malformed Functions and Calculations

CSS functions like calc(), rgb(), var(), and minmax() require precise syntax. Stylelint ensures arguments and operators follow correct mathematical and formatting rules.

  • Caught Error: Writing calc(100% - 20px) without spaces around the minus sign (which breaks in standard CSS) or supplying incorrect argument counts to color functions, such as rgb(255, 0).

5. Unclosed Strings, Brackets, and Blocks

Structural issues break stylesheet parsing and cause cascading failures that affect unrelated elements lower in the file. Stylelint immediately catches:

  • Unclosed curly braces ({})
  • Missing or unclosed quotation marks in strings or URLs (e.g., background-image: url('image.png);)
  • Unclosed parentheses in function calls.

6. Invalid at-Rules and Media Queries

At-rules like @media, @supports, and @keyframes require specific structures. Stylelint validates both the identifier and the conditions within them.

  • Caught Error: Misspelling queries like @media scren and (max-widh: 768px) or declaring @keyframe instead of @keyframes.

7. Duplicate Properties and Selectors

While technically parseable by browsers, duplicate declarations within the same rule block often indicate copy-paste mistakes or unintended overrides. Stylelint flags identical properties declared twice within the same selector block unless specifically configured to allow standard fallback patterns.