Your project grows, and CSS code turns into chaos: duplicate selectors, invalid properties, messy ordering. Even experienced developers spend hours on code review, yet errors still slip into production. Stylelint is the de facto standard for automatic CSS linting, but configuration requires understanding of syntaxes and rules. We implement Stylelint in projects: configure it to your style guide, integrate with Prettier, CI/CD, and editor. In 1-2 days you get clean, consistent CSS code that the linter checks automatically.
Why Stylelint instead of Prettier?
Stylelint and Prettier solve different problems. Prettier automatically formats indentation, quotes, line breaks. Stylelint finds errors: non-existent CSS properties, incorrect units (px instead of rem), duplicate selectors, ordering violations. In practice, they complement each other: Prettier makes code uniform, Stylelint makes it correct. Without Stylelint, your project risks bugs that no code review will catch.
What problems does Stylelint solve?
Real errors that Stylelint catches automatically:
-
color-no-invalid-hex— invalid hex colors (#abcde) -
unit-no-unknown— unknown units (20pxx) -
property-no-unknown— non-existent properties (dispay: flex) -
declaration-block-no-duplicate-properties— duplicate properties in one block -
no-duplicate-selectors— identical selectors in different places -
selector-class-pattern— naming convention violations (BEM, kebab-case)
From our practice: for a large e-commerce client over a month, we found 150+ duplicate selectors that increased CSS weight by 30%. After configuring Stylelint, such errors dropped to zero. Saving on fixing just those duplicates was about $2000 considering developer time.
How we set up Stylelint: a detailed case
For a React project using Emotion, we add @stylelint/postcss-css-in-js, write rules for styled-components, disable checks for properties set via styles object. Result: the linter checks all CSS-in-JS calls like regular CSS files. As stated in the official documentation, Stylelint is a "mighty, modern linter that helps you avoid errors and enforce conventions in your stylesheets" (Stylelint documentation).
Installation
npm install --save-dev stylelint stylelint-config-standard stylelint-config-standard-scss stylelint-order npm install --save-dev @stylelint/postcss-css-in-js postcss-syntax Example configuration for SCSS with property order
{ "extends": [ "stylelint-config-standard", "stylelint-config-standard-scss" ], "plugins": ["stylelint-order"], "rules": { "color-named": "never", "color-no-invalid-hex": true, "unit-no-unknown": true, "property-no-unknown": true, "declaration-block-no-duplicate-properties": true, "no-duplicate-selectors": true, "selector-class-pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$", "order/properties-order": [ "content", "position", "top", "right", "bottom", "left", "z-index", "display", "flex", "flex-direction", "flex-wrap", "align-items", "justify-content", "grid", "grid-template", "width", "min-width", "max-width", "height", "min-height", "max-height", "margin", "margin-top", "margin-right", "margin-bottom", "margin-left", "padding", "padding-top", "padding-right", "padding-bottom", "padding-left", "border", "border-radius", "background", "background-color", "color", "font", "font-size", "font-weight", "line-height", "transition", "animation", "cursor", "pointer-events", "opacity", "overflow", "visibility" ] } } We configure property order to match your style guide. You can simplify to grouping without strict order inside groups. For configuration we use the stylelint-order plugin: in the order/properties-order rule you can set exact order or grouping.
Tailwind CSS
For Tailwind we disable checks for at-rules:
{ "extends": ["stylelint-config-standard", "stylelint-config-tailwindcss"], "rules": { "at-rule-no-unknown": [true, { "ignoreAtRules": ["tailwind", "apply", "variants", "responsive", "screen", "layer"] }] } } CSS-in-JS (styled-components, emotion)
{ "overrides": [ { "files": ["**/*.{js,jsx,ts,tsx}"], "customSyntax": "@stylelint/postcss-css-in-js", "rules": { "color-named": "never", "property-no-unknown": true } } ] } More about CSS-in-JS can be read on Wikipedia.
Editor Integration
Install the stylelint.vscode-stylelint extension and configure settings.json, disabling the built-in VS Code linter for CSS/SCSS. Enable auto-fix on save.
How Stylelint speeds up code review?
Compare: without a linter, a developer spends 10-15 minutes checking styles in a pull request. Stylelint catches 95% of issues automatically; only architectural questions remain in code review. According to our measurements, a team of 5 saves up to 80% of time on CSS reviews. With an average rate of $50/hour, that saves about $6000 per month. Moreover, the cost of fixing one CSS error after release can reach $200, and Stylelint prevents such costs.
| Parameter | Without Stylelint | With Stylelint |
|---|---|---|
| Errors in styles | 15-20 per PR | 1-2 (missed by linter) |
| Code review time | 15 min | 2 min |
| Bugs in production | regularly | isolated cases |
Stylelint finds errors 5 times faster than manual review: an average PR is checked in 2 minutes instead of 15. Time savings on code review up to 80%. We guarantee that after our setup, the number of CSS errors will drop by 90%. Get a consultation on Stylelint configuration for your project.
Typical mistakes when setting up Stylelint
- Conflict with Prettier: if you don't disable redundant rules, they start contradicting each other. Use
stylelint-config-prettier. - Ignoring preprocessors: for SCSS you need the
stylelint-config-standard-scssconfig, otherwise the linter won't understand nesting. - Missing pre-commit hook: without husky and lint-staged, the linter runs only manually or in CI—value decreases.
What's included in Stylelint setup?
- Configuration file
.stylelintrc.jsonwith custom rules - Integration with Prettier (if needed)
- Pre-commit hook (husky + lint-staged)
- CI scripts (command
npm run lint:cssin pipeline) - Documentation of rules and exceptions
- Team training (30-minute demo)
Process
- Analysis — study current code, preprocessors, style guide, frameworks (Tailwind? CSS-in-JS?).
- Config selection — standard, scss, tailwindcss, css-modules — or combination.
- Rule configuration — adapt to your naming, property order, project specifics.
- Integration — add to bundler (webpack/vite), pre-commit hook (husky), CI (GitHub Actions/GitLab CI).
- Testing — run linter on entire project, fix initial errors, document.
- Documentation — deliver config, developer instructions, recommendations for refinement.
Estimated timelines
| Step | Time |
|---|---|
| Basic setup (CSS/SCSS) | 1-2 hours |
| Adding property order and custom patterns | +1 hour |
| Integration with CI and pre-commit | +1 hour |
| Configuration for CSS-in-JS or Tailwind | +1-2 hours |
Total: from 1 to 2 working days depending on complexity. Contact us—we'll assess your code and prepare a turnkey config.