Stylelint

Commands

Task	Command
Lint styles (via lint task)	pnpm lint
Lint only Stylelint	pnpm lint:stylelint
Lint a specific file	pnpm exec stylelint <path>
Lint with auto-fix	pnpm exec stylelint --fix <path>

Default action: When asked to "lint styles" or "run Stylelint" without further qualification, prefer pnpm lint if it includes Stylelint, otherwise fall back to the dedicated Stylelint script.

Commands and glob patterns vary across projects. Always check package.json scripts before running — pnpm lint:stylelint is the norm in some repos, pnpm stylelint in others.

Before linting — explore the project first

Before running or modifying Stylelint, read the project's config file (typically .stylelintrc or .stylelintrc.json) to understand:

• Which shareable configs are extended (e.g. stylelint-config-standard-scss, stylelint-config-clean-order)
• Which plugins are installed and active — cross-reference with package.json devDependencies to see the full set
• Which rules are customized, disabled (null), or overridden beyond the extended configs
• Whether strict reporting options are enabled (reportNeedlessDisables, reportInvalidScopeDisables, reportDescriptionlessDisables, reportUnscopedDisables) — these turn disable-comment misuse into errors
• Whether caching is enabled ("cache": true) — if so, pass --cache when running via pnpm exec stylelint directly

Also check package.json scripts to understand what glob patterns are passed (e.g. "**/*.scss") and how Stylelint is wired into the overall lint pipeline for this project.

Configuration format

Projects use a .stylelintrc (JSON, no extension) config file at the repo root. When writing or modifying configs, keep the JSON format consistent with what the project already uses.

Relationship with Prettier

Stylelint and Prettier have a strict separation of concerns:

• Stylelint — style quality, property ordering, deprecated values, SCSS-specific rules
• Prettier — all formatting (indentation, spacing, line length, etc.)

Never add formatting rules to Stylelint. Never use stylelint --fix to fix formatting — use pnpm format:write for that.

Disabling rules inline

When a Stylelint disable comment is necessary, follow these guidelines:

• Use the most targeted scope: single-line (// stylelint-disable-next-line) is preferred over block-level (/* stylelint-disable */)
• Always name the specific rule(s) being disabled — bare stylelint-disable without a rule name is reported as an error where reportUnscopedDisables is active
• Add a comment explaining why the disable is needed
• If reportNeedlessDisables is active, never disable a rule that isn't actually triggering on that line

Workflow notes

• Run Stylelint before every commit alongside pnpm format:write and pnpm lint:eslint
• If Stylelint fails in CI, fix the issues locally and confirm with the same lint command before committing
• Prefer fixing the root cause over suppressing with disable comments
• Auto-fix (--fix) only corrects a subset of rules — review any remaining errors manually after running it