Stylelint

Stylelint for Stylesheets in .NET Repositories

Trigger On

• the repo has stylelint.config.*, .stylelintrc*, or CSS and SCSS assets under frontend folders
• the user asks for CSS linting, duplicate style cleanup, naming convention enforcement, or design-system guardrails
• the repo needs a stylesheet gate beyond formatting alone

Do Not Use For

• JavaScript or TypeScript ownership; route that to eslint or biome
• runtime accessibility, performance, SEO, or header checks; route that to webhint
• repos that intentionally use only Biome for CSS linting and do not want a separate stylesheet linter

Inputs

• the nearest AGENTS.md
• package.json
• stylelint.config.* or .stylelintrc*
• the stylesheet file types in scope: CSS, SCSS, Less, embedded styles, or generated output

Workflow

1. Confirm what Stylelint should own:

• plain CSS only
• CSS plus SCSS
• embedded styles in HTML, Markdown, or framework files

2. Prefer repo-local installation and checked-in config. 3. Start from a known shared config such as stylelint-config-standard, then add syntax-specific packages only when the repo truly needs them. 4. Add repeatable scripts to package.json, for example:

• stylelint "**/*.{css,scss}"
• stylelint "**/*.{css,scss}" --fix

5. Keep ignore patterns explicit so build output, vendored assets, and generated CSS do not pollute the signal. 6. Treat autofix as controlled cleanup:

• run on a bounded scope first
• inspect the diff
• rerun the frontend build if the repo compiles styles

7. Use Stylelint for semantic CSS and selector policy, not as a replacement for site-level audits.

Bootstrap When Missing

1. Detect current state:

• rg --files -g 'package.json' -g 'stylelint.config.*' -g '.stylelintrc*'
• rg -n '"stylelint"|"stylelint-config-" --glob 'package.json' .

2. Prefer a repo-local install:

• npm install --save-dev stylelint stylelint-config-standard

3. Add syntax packages only when the repo needs them for SCSS or embedded styles. 4. Create or refine stylelint.config.js, stylelint.config.mjs, or the existing config format. 5. Add repeatable commands to AGENTS.md and package.json, then verify with:

• npx stylelint "**/*.{css,scss}"
• npx stylelint "**/*.{css,scss}" --fix

6. Return status: configured if Stylelint is now wired and repeatable, or status: improved if the existing baseline was tightened. 7. Return status: not_applicable only when another documented tool already owns stylesheet linting and migration is not requested.

Handle Failures

• Unknown rule usually means the config expects a plugin or a different Stylelint major version.
• Unknown word on SCSS, Vue, or mixed-content files usually means the repo needs the matching custom syntax package instead of plain CSS parsing.
• Massive autofix churn usually means generated assets or third-party CSS slipped into the lint target.
• Design-system rule noise should be handled by tuning the checked-in config, not by skipping the linter entirely.

Current 17.13 Guidance

• Stylelint 17.13.0 is a bug-fix release. It fixes false negatives for non-consecutive duplicate properties when consecutive-duplicate ignores are configured, false positives for selector-max-type with nested selectors, and false positives for selector-type-no-unknown around install.
• Stylelint 17.8.0 also added languageOptions.directionality, property-layout-mappings, relative-selector-nesting-notation, and selector-no-deprecated. Re-run the repo baseline after upgrading so any new selector or layout findings are reviewed instead of preserved by default.
• Use languageOptions.directionality explicitly when the repo styles bidirectional UI or logical properties. That keeps direction-sensitive rules aligned with the intended writing direction rather than inferred behavior.
• The earlier *syntax deprecation under declaration-property-value-no-unknown still matters on the 17.x line. If the repo still relies on those options, move the compatibility into customSyntax or parser selection instead of extending deprecated rule config.
• Keep repo ignores focused on generated or vendored assets. Re-check any broad ignore globs after upgrading so they are not masking selector or layout regressions that the new rules now catch.

Official Sources

• Stylelint 17.13.0 release notes
• references/release-notes.md

Deliver

• explicit stylesheet lint ownership
• checked-in config and repeatable commands
• clear scope boundaries for CSS, SCSS, and generated assets

Validate

• the lint target matches the repo's real stylesheet sources
• ignores exclude generated or vendored assets
• Stylelint ownership does not conflict with Biome without an explicit plan
• fixes were verified against the repo's stylesheet build flow when one exists

Ralph Loop

1. Plan: analyze current state, target outcome, constraints, and risks. 2. Execute one step and produce a concrete delta. 3. Review the result and capture findings. 4. Apply fixes in small batches and rerun checks. 5. Update the plan after each iteration. 6. Repeat until outcomes are acceptable. 7. If a dependency is missing, bootstrap it or return status: not_applicable with a reason.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current step
• actions_taken: concrete changes made
• verification: commands, checks, or review evidence
• remaining: unresolved items or none

Example Requests

• "Add Stylelint for the SCSS in this ASP.NET Core app."
• "Block duplicate selectors and invalid CSS in CI."
• "Fix the current Stylelint violations without touching generated CSS."

References

• release-notes.md - Current 17.13.0 and 17.8.0 release changes that matter for repo config, rule tuning, and selector/layout validation

Stylelint 17.13.0 Notes

Use this note when a repo already has Stylelint wired and you need to refresh config or validation behavior after the 17.13.0 release. It also preserves the earlier 17.8 notes because those introduced new rule/config surfaces that still matter during upgrades.

What changed that matters for repository maintenance

• 17.13.0 fixes declaration-block-no-duplicate-properties false negatives for interleaved non-consecutive duplicates when consecutive-duplicate ignores are configured.
• 17.13.0 fixes selector-max-type false positives for nested selectors.
• 17.13.0 fixes selector-type-no-unknown false positives for install.
• languageOptions.directionality lets the config declare writing direction explicitly, which matters when a repo uses logical properties or bidirectional UI conventions.
• property-layout-mappings adds a new rule for property-to-layout relationships, so repos with strict layout policy may need to tune or adopt it during upgrade.
• relative-selector-nesting-notation gives repos a rule for nested selector notation, which can surface issues in Sass or nested CSS codebases.
• selector-no-deprecated adds a dedicated check for deprecated selector usage, which may reveal cleanup work in older style baselines.

Practical repo guidance

1. Check whether the config still uses deprecated *syntax options. 2. Replace those options with explicit syntax handling via customSyntax or the repo's selected syntax package. 3. If the repo uses direction-sensitive styles, set languageOptions.directionality deliberately instead of relying on implied defaults. 4. Re-run the lint baseline and remove stale ignores or waivers that only existed to compensate for older false positives or now-covered deprecated selectors. 5. If the repo introduces property-layout-mappings or relative-selector-nesting-notation, verify the new warnings map to real design-system policy rather than parser noise.

Source

• Stylelint 17.13.0 release notes
• Stylelint 17.8.0 release notes