@simonsmith/stylelint-component-custom-property

v2.1.0

Published

10 months ago

Stylelint plugin that validates CSS custom properties in CSS modules to ensure they follow a component-based naming convention.

0High
0Medium
0Low

simonsmith

stylelint-component-custom-property

Stylelint plugin that validates CSS custom properties in CSS modules to ensure they follow a component-based naming convention.

npm version

Why?

When working with CSS modules, components often expose custom properties as a public API that can be overridden by parent components. This plugin validates that these public custom properties follow a consistent naming convention based on the component name.

For example, if your CSS module is named Button.module.css:

.button {
  /* Public API - validated */
  background-color: var(--Button-primary-color, #007bff);

  /* Private properties - not validated */
  --internal-state: active;
}

This convention helps with:

Consistency: All public custom properties follow the same naming pattern
Clarity: It's immediately clear which properties are part of the component's public API
Avoiding conflicts: Prevents naming collisions when components are nested
API documentation: Fallback values serve as default values and documentation

Installation

npm install --save-dev @simonsmith/stylelint-component-custom-property

yarn add --dev @simonsmith/stylelint-component-custom-property

pnpm add --save-dev @simonsmith/stylelint-component-custom-property

Usage

Add the plugin to your stylelint configuration:

{
  "plugins": ["@simonsmith/stylelint-component-custom-property"],
  "rules": {
    "@simonsmith/stylelint-component-custom-property": true
  }
}

Configuration

The rule accepts different validation types:

Basic validation (default)

Validates only that custom properties match the component name from the filename:

{
  "plugins": ["@simonsmith/stylelint-component-custom-property"],
  "rules": {
    "@simonsmith/stylelint-component-custom-property": true
  }
}

SUIT CSS validation

Validates SUIT CSS naming conventions:

{
  "plugins": ["@simonsmith/stylelint-component-custom-property"],
  "rules": {
    "@simonsmith/stylelint-component-custom-property": {
      "validationType": "suitcss"
    }
  }
}

Due to the potential ambiguity of the validation pattern in SUIT CSS this option prefers to lean on being more relaxed rather than incorrectly flagging properties as invalid. See the unit tests for what it covers currently

Custom pattern validation

Use your own regular expression for suffix validation:

{
  "plugins": ["@simonsmith/stylelint-component-custom-property"],
  "rules": {
    "@simonsmith/stylelint-component-custom-property": {
      "validationType": /^-[a-z][a-zA-Z]*$/
    }
  }
}

Disable the rule

{
  "rules": {
    "@simonsmith/stylelint-component-custom-property": false
  }
}

How it works

The plugin:

Only applies to CSS modules - files ending with .module.css
Validates public API custom properties - ensures they start with --ComponentName-
Ignores private custom properties - allows any naming for internal use
Autofix - can automatically correct invalid prefixes in API declarations

What gets validated

The plugin validates custom properties only when they're used as public API declarations.

API declarations (validated)

Custom properties used in var() functions with fallback values are treated as component API declarations:

.container {
  gap: var(--Button-spacing, 1rem);
  width: var(--Button-max-width, 320px);
}

Private properties (ignored)

Direct custom property assignments are considered private implementation details:

.button {
  --internal-state: hover;
  --computed-size: calc(100% - 2rem);
}

Property consumption (ignored)

Custom properties used without fallbacks are considered consumption of existing properties:

.button {
  color: var(--theme-primary);
  margin: var(--Button-spacing);
}

Examples

Valid

Button.module.css

.button {
  /* Public API declarations - validated */
  background-color: var(--Button-primary-color, #007bff);
  padding: var(--Button-padding, 0.5rem 1rem);

  /* Private properties - not validated */
  --internal-state: default;
  --computed-width: calc(100% - 2rem);

  /* Consuming existing properties - not validated */
  margin: var(--global-spacing);
  font-family: var(--theme-font);
}

/* Overriding child component APIs - not validated */
.button-container {
  --Icon-size: 16px;
  --Tooltip-background: var(--Button-primary-color);
}

Invalid