{"id":31741021,"url":"https://github.com/simonsmith/stylelint-component-custom-property","last_synced_at":"2026-01-20T17:01:17.267Z","repository":{"id":313218913,"uuid":"1049368040","full_name":"simonsmith/stylelint-component-custom-property","owner":"simonsmith","description":"Stylelint plugin that validates CSS custom properties in CSS modules to ensure they follow a component-based naming convention.","archived":false,"fork":false,"pushed_at":"2025-09-08T13:12:47.000Z","size":125,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-16T23:55:20.998Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonsmith.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-02T21:54:50.000Z","updated_at":"2025-09-08T13:12:49.000Z","dependencies_parsed_at":"2025-09-04T17:26:45.578Z","dependency_job_id":"71b3d7f2-44ee-49e6-a465-6ae1a3562dff","html_url":"https://github.com/simonsmith/stylelint-component-custom-property","commit_stats":null,"previous_names":["simonsmith/stylelint-component-custom-property"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/simonsmith/stylelint-component-custom-property","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fstylelint-component-custom-property","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fstylelint-component-custom-property/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fstylelint-component-custom-property/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fstylelint-component-custom-property/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonsmith","download_url":"https://codeload.github.com/simonsmith/stylelint-component-custom-property/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fstylelint-component-custom-property/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T10:31:19.112Z","updated_at":"2026-01-20T17:01:17.236Z","avatar_url":"https://github.com/simonsmith.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stylelint-component-custom-property\n\nStylelint plugin that validates CSS custom properties in CSS modules to ensure they follow a component-based naming convention.\n\n![npm version](https://img.shields.io/npm/v/@simonsmith/stylelint-component-custom-property)\n![CI](https://github.com/simonsmith/stylelint-component-custom-property/actions/workflows/ci.yml/badge.svg)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Why?](#why)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n  - [Basic validation (default)](#basic-validation-default)\n  - [SUIT CSS validation](#suit-css-validation)\n  - [Custom pattern validation](#custom-pattern-validation)\n  - [Disable the rule](#disable-the-rule)\n- [How it works](#how-it-works)\n  - [What gets validated](#what-gets-validated)\n    - [API declarations (validated)](#api-declarations-validated)\n    - [Private properties (ignored)](#private-properties-ignored)\n    - [Property consumption (ignored)](#property-consumption-ignored)\n- [Examples](#examples)\n  - [Valid](#valid)\n  - [Invalid](#invalid)\n  - [Filename warnings](#filename-warnings)\n- [Autofix](#autofix)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Why?\n\nWhen 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.\n\nFor example, if your CSS module is named `Button.module.css`:\n\n```css\n.button {\n  /* Public API - validated */\n  background-color: var(--Button-primary-color, #007bff);\n\n  /* Private properties - not validated */\n  --internal-state: active;\n}\n```\n\nThis convention helps with:\n\n- **Consistency**: All public custom properties follow the same naming pattern\n- **Clarity**: It's immediately clear which properties are part of the component's public API\n- **Avoiding conflicts**: Prevents naming collisions when components are nested\n- **API documentation**: Fallback values serve as default values and documentation\n\n## Installation\n\n```bash\nnpm install --save-dev @simonsmith/stylelint-component-custom-property\n```\n\n```bash\nyarn add --dev @simonsmith/stylelint-component-custom-property\n```\n\n```bash\npnpm add --save-dev @simonsmith/stylelint-component-custom-property\n```\n\n## Usage\n\nAdd the plugin to your stylelint configuration:\n\n```json\n{\n  \"plugins\": [\"@simonsmith/stylelint-component-custom-property\"],\n  \"rules\": {\n    \"@simonsmith/stylelint-component-custom-property\": true\n  }\n}\n```\n\n## Configuration\n\nThe rule accepts different validation types:\n\n### Basic validation (default)\n\nValidates only that custom properties match the component name from the filename:\n\n```json\n{\n  \"plugins\": [\"@simonsmith/stylelint-component-custom-property\"],\n  \"rules\": {\n    \"@simonsmith/stylelint-component-custom-property\": true\n  }\n}\n```\n\n### SUIT CSS validation\n\nValidates [SUIT CSS naming conventions](https://github.com/suitcss/suit/blob/master/doc/naming-conventions.md#variables):\n\n```json\n{\n  \"plugins\": [\"@simonsmith/stylelint-component-custom-property\"],\n  \"rules\": {\n    \"@simonsmith/stylelint-component-custom-property\": {\n      \"validationType\": \"suitcss\"\n    }\n  }\n}\n```\n\nDue to the potential ambiguity of the validation pattern in SUIT CSS this option prefers to lean on being more relaxed rather than incorrectly\nflagging properties as invalid. See [the unit tests](https://github.com/simonsmith/stylelint-custom-property-prefix/blob/e8022cc57466d91de8d868781816a080855d17dd/src/validate.test.ts#L21-L43) for what it covers currently\n\n### Custom pattern validation\n\nUse your own regular expression for suffix validation:\n\n```json\n{\n  \"plugins\": [\"@simonsmith/stylelint-component-custom-property\"],\n  \"rules\": {\n    \"@simonsmith/stylelint-component-custom-property\": {\n      \"validationType\": /^-[a-z][a-zA-Z]*$/\n    }\n  }\n}\n```\n\n### Disable the rule\n\n```json\n{\n  \"rules\": {\n    \"@simonsmith/stylelint-component-custom-property\": false\n  }\n}\n```\n\n## How it works\n\nThe plugin:\n\n- **Only applies to CSS modules** - files ending with `.module.css`\n- **Validates public API custom properties** - ensures they start with `--ComponentName-`\n- **Ignores private custom properties** - allows any naming for internal use\n- **Autofix** - can automatically correct invalid prefixes in API declarations\n\n### What gets validated\n\nThe plugin validates custom properties only when they're used as **public API declarations**.\n\n#### API declarations (validated)\n\nCustom properties used in `var()` functions **with fallback values** are treated as component API declarations:\n\n```css\n.container {\n  gap: var(--Button-spacing, 1rem);\n  width: var(--Button-max-width, 320px);\n}\n```\n\n#### Private properties (ignored)\n\nDirect custom property assignments are considered private implementation details:\n\n```css\n.button {\n  --internal-state: hover;\n  --computed-size: calc(100% - 2rem);\n}\n```\n\n#### Property consumption (ignored)\n\nCustom properties used without fallbacks are considered consumption of existing properties:\n\n```css\n.button {\n  color: var(--theme-primary);\n  margin: var(--Button-spacing);\n}\n```\n\n## Examples\n\n### Valid\n\n**Button.module.css**\n\n```css\n.button {\n  /* Public API declarations - validated */\n  background-color: var(--Button-primary-color, #007bff);\n  padding: var(--Button-padding, 0.5rem 1rem);\n\n  /* Private properties - not validated */\n  --internal-state: default;\n  --computed-width: calc(100% - 2rem);\n\n  /* Consuming existing properties - not validated */\n  margin: var(--global-spacing);\n  font-family: var(--theme-font);\n}\n\n/* Overriding child component APIs - not validated */\n.button-container {\n  --Icon-size: 16px;\n  --Tooltip-background: var(--Button-primary-color);\n}\n```\n\n### Invalid\n\n**Button.module.css**\n\n```css\n.button {\n  /* Wrong prefix in API declaration */\n  background: var(--wrong-color, red);\n\n  /* No prefix in API declaration */\n  padding: var(--spacing, 1rem);\n}\n```\n\n## Autofix\n\nThe plugin supports stylelint's `--fix` option and will automatically correct invalid custom property prefixes in API declarations:\n\n```bash\nstylelint \"**/*.module.css\" --fix\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonsmith%2Fstylelint-component-custom-property","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonsmith%2Fstylelint-component-custom-property","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonsmith%2Fstylelint-component-custom-property/lists"}