DOCSEARCHbyAlgolia
Submit Docs

Stylelint Documentation

website·Indexed 40 days ago

https://stylelint.io/

A linter for CSS and related languages. This documentation provides a comprehensive user guide for rules, including selector validation, unit and value constraints, and shorthand property management, as well as version history and contribution guidelines.

Tokens
72.7K
Snippets
509
Records
692
Agent score
74%

What's inside Stylelint

  1. Overview of Stylelint features and capabilities

    Stylelint is a CSS linter used to avoid errors and enforce coding conventions. Its core capabilities include:

    • Rule Set: Over 100 built-in rules for modern CSS syntax.
    • Extensibility: Supports plugins for custom rules and shareable configurations that can be created or extended.
    • Automation: Automatically fixes problems where possible.
    • Language Support: Can be extended to parse CSS-like languages such as SCSS, Sass, Less, and SugarSS.
    • Style Extraction: Capable of extracting embedded styles from HTML, Markdown, and CSS-in-JS template literals.

  2. Disallow unknown pseudo-class selectors with selector-pseudo-class-no-unknown

    The selector-pseudo-class-no-unknown rule prevents the use of pseudo-class selectors that are not defined in the CSS Specifications (including Editor's Drafts). It automatically ignores vendor-prefixed pseudo-class selectors. This rule supports one message argument to customize the reported unknown pseudo-class.
    {
  "selector-pseudo-class-no-unknown": true
}

  3. Disallow redundant longhand properties with declaration-block-no-redundant-longhand-properties

    The declaration-block-no-redundant-longhand-properties rule prevents the use of multiple longhand properties when they can be more concisely written as a single shorthand property. The rule triggers only if all the longhand properties that the shorthand would set are present and their values are not CSS-wide keywords (e.g., initial, inherit).

    Note: Redundancy is determined by the CSS specification regardless of specific browser behavior. For example, even if a shorthand like flex has known bugs in older browsers (like IE), the rule will still flag the longhand equivalent as redundant.

    Supported shorthand properties include:

    • Layout/Box Model: margin, padding, gap, inset, outline, flex, grid (and their block/inline variants).
    • Borders: border, border-width, border-style, border-color, border-radius, border-image (and their directional variants).
    • Typography: font, font-variant, font-synthesis, text-decoration, text-emphasis.
    • Visuals: background, animation, transition, mask, overflow, overscroll-behavior.
    • Others: column-rule, columns, list-style, place-content, place-items, place-self, scroll-margin, scroll-padding (and their block/inline variants).
    /* Problem: Redundant longhands */
a {
  padding-top: 1px;
  padding-right: 2px;
  padding-bottom: 3px;
  padding-left: 4px;
}

/* Solution: Use shorthand */
a {
  padding: 1px 2px 3px 4px;
}

  4. Prevent descending specificity with no-descending-specificity

    The no-descending-specificity rule prevents selectors with lower specificity from appearing after selectors with higher specificity that they override. This ensures that stylesheets are more legible by aligning source order with specificity priority.

    How it works:

    • The rule compares the last compound selector of every full selector against others that end in the same way (e.g., .foo .bar is compared to .bar and #baz .bar).
    • Selectors targeting pseudo-elements are not compared to those without them.
    • Comparisons only occur within the same media context.
    • It adheres to the CSS Nesting specification for calculating specificity of the nesting selector (&).

    Important Constraint: This rule is intended for standard CSS only. Do not enable it for CSS-like languages such as SCSS or Less.

    /* Invalid: Higher specificity comes before lower specificity */
#container a { top: 10px; }
a { top: 0; }

  5. Enforce flow-relative or physical layout units with unit-layout-mappings

    The unit-layout-mappings rule ensures that units used in CSS layout mappings are either flow-relative (e.g., vi, vb, cqi, cqb) or physical (e.g., vw, vh, cqw, cqh). Flow-relative units adapt to different writing modes and text directions, which is essential for internationalization and complements flow-relative properties like inline-size and block-size.

  6. Extend Stylelint functionality with plugins

    Plugins add new rules to Stylelint. Key plugins include:

    • Architecture/Methodology: stylelint-selector-bem-pattern (BEM), stylelint-react-native (React Native), and stylelint-plugin-defensive-css.
    • Browser Compatibility: stylelint-no-browser-hacks, stylelint-no-unsupported-browser-features, and stylelint-plugin-use-baseline.
    • Ordering: stylelint-order for enforcing specific property/rule order.
    • Pre-processors: stylelint-scss (SCSS) and stylelint-stylus (Stylus).
    • Stylistic: @stylistic/stylelint-plugin (re-introduces rules removed in Stylelint 16.0.0).
    • Other: stylelint-gamut (color spaces), stylelint-no-indistinguishable-colors, stylelint-no-unresolved-module (imports), and stylelint-plugin-logical-css (logical properties).

  7. Enforce flow-relative or physical layout mappings for value keywords

    The value-keyword-layout-mappings rule ensures that value keywords (like left, top, inline-start, block-start) are consistently either flow-relative or physical.

    • Flow-relative keywords (e.g., inline-start, block-start, inline) adapt to writing modes and text directions, which is essential for internationalization.
    • Physical keywords (e.g., left, top, horizontal) are tied to the physical dimensions of the screen.

    This rule supports two message arguments: the disallowed mapping and the keyword, or the physical keyword and its flow-relative equivalent.

  8. Understand Stylelint contributor roles and responsibilities

    Stylelint defines three primary roles for those involved in the project:

    1. Contributors: Anyone involved with Stylelint. They report bugs, request features, improve documentation, fix bugs, add features, and improve code. All proposed changes require consensus to move forward.
    2. Members: Volunteers who triage issues, review pull requests, and ensure code quality.
    3. Owners: Administrative governors who manage user roles and conduct releases.

  9. Enforce quotation marks for font family names with stylelint

    The font-family-name-quotes rule requires or disallows quotes for font family names in font and font-family properties. It ignores $sass, @less, and var(--custom-property) variable syntaxes.

    Crucially, this rule always enforces no quotes around generic font keywords (e.g., inherit, serif, sans-serif, cursive, fantasy, system-ui, monospace, ui-serif, ui-sans-serif, ui-monospace, ui-rounded, emoji, math, fangsong) and vendor-prefixed system fonts (e.g., -apple-system, BlinkMacSystemFont).

    Note: This rule does not currently support CSS escape sequences; font names containing characters that require escaping must be wrapped in quotes.

  10. Stylelint core capabilities and design goals

    Stylelint serves as a linter and validator for CSS with the following core characteristics:

    • Complete: Provides built-in rules for standard CSS syntax to avoid errors and enforce conventions.
    • Configurable: Offers options to customize the linter to meet specific project needs, including overlapping configurable rules.
    • Robust: Maintains a comprehensive test suite with over 95% coverage and a wide range of rule fixtures.
    • Consistent: Follows consistent conventions for behavior, naming, and documentation across rules and options.
    • Performant: Designed for speed with built-in means to benchmark and improve performance.

  11. Understand the Stylelint Result object structure

    Each item in the results array of the lint() return value contains detailed information about a specific file or source.
    {
  "source": "path/to/file.css",
  "errored": true,
  "warnings": [
    {
      "line": 3,
      "column": 12,
      "endLine": 4,
      "endColumn": 15,
      "rule": "block-no-empty",
      "severity": "error",
      "text": "You should not have an empty block (block-no-empty)"
    }
  ],
  "deprecations": [
    { "text": "...", "reference": "..." }
  ],
  "invalidOptionWarnings": [
    { "text": "..." }
  ],
  "ignored": true,
  "autofixed": true
}

  12. Limit selector specificity with selector-max-specificity

    The selector-max-specificity rule ensures that CSS selectors do not exceed a defined specificity threshold. This is useful for maintaining a flat specificity hierarchy and avoiding overly specific selectors that are hard to override.

    Key behaviors:

    • Each selector in a selector list is evaluated separately.
    • Selectors with variable interpolation (e.g., #{$var}, @{var}, $(var)) are ignored.
    • It adheres to the CSS Nesting specification; the nesting selector (&) takes the specificity of the largest complex selector in the parent's list.
    • Warning: This rule is intended for standard CSS. It should not be enabled for CSS-like languages such as SCSS or Less.