@maz-ui/stylelint-config

@maz-ui/stylelint-config

Reusable Stylelint configuration for Vue/Nuxt/JS/TS projects, with first-class Tailwind CSS v4 support, RTL-friendly logical properties, and SCSS opt-in.

Features

• 🚀 Stylelint Standard base — opinionated, maintained by the Stylelint team
• 🎨 Tailwind v4 — at-rule whitelist, validation rules via stylelint-plugin-tailwindcss (3 strictness levels)
• 🌍 RTL-friendly — logical properties via stylelint-use-logical-spec
• 🔠 Property ordering — Recess-based by default, alphabetical or off
• 💚 Vue/HTML/SCSS — auto-detected from your package.json
• 🛠 Configurable — toggle features, override rules, append per-file overrides

Installation

pnpm add -D @maz-ui/stylelint-config stylelint

Basic usage

// stylelint.config.mjs
import { defineConfig } from '@maz-ui/stylelint-config'

export default defineConfig()

Vue, Tailwind and SCSS are auto-detected from your package.json.

Options

defineConfig({
  vue: true, // auto-detected from `vue`/`nuxt` deps
  html: false,
  tailwind: true, // auto-detected from `tailwindcss` dep — see "Tailwind" below
  scss: false, // auto-detected from `sass`/`sass-embedded`/`node-sass`
  logical: true, // recommend logical CSS properties (RTL-friendly)
  order: 'recess', // 'recess' | 'alphabetical' | false

  ignores: ['**/legacy/**'],
  rules: {
    'no-descending-specificity': null,
  },
  overrides: [
    { files: ['**/*.legacy.css'], rules: { 'color-no-invalid-hex': null } },
  ],
  extends: ['stylelint-config-clean-order'], // layer extra shareable configs
  logLevel: 'default', // 'silent' | 'default' | 'debug' | 'verbose' — see "Logging" below
})

Logging

The preset can log what it resolves and applies, which is handy when you don't understand why a rule is on or off. Pass a logLevel (powered by @maz-ui/node's consola-based logger):

defineConfig({ logLevel: 'debug' })

Tailwind support

[!IMPORTANT] The plugin rules in 'recommended' and 'strict' auto-resolve your project's Tailwind runtime from each linted file's path. Projects with a v4 prefix (maz:, tw:, …), a non-standard entry CSS, or a monorepo layout where Tailwind isn't where the plugin expects produce false positives. 'minimal' is the safe default. Opt into 'recommended' only if your project sits in the plugin's happy path.

Plugin rules come from stylelint-plugin-tailwindcss and support both Tailwind v3 and v4.

Property ordering

To swap recess for another shareable order config (e.g. stylelint-config-clean-order), disable the built-in strategy and extend yours:

defineConfig({
  order: false,
  extends: ['stylelint-config-clean-order'],
})

Layering shareable configs

The extends option appends entries after the built-ins, so user configs win Stylelint's cascade. Common cases:

defineConfig({
  extends: [
    'stylelint-config-clean-order', // alternative property order
    '@stylistic/stylelint-config', // restore stylistic rules retired from core
  ],
})

Auto-detection caveat (monorepos)

Auto-detection reads the package.json in process.cwd() only. In a monorepo where tailwindcss, vue or sass are hoisted to the root and missing from a sub-package's package.json, detection fails when Stylelint runs from that sub-package.

In monorepos, set the relevant flags explicitly:

defineConfig({ vue: true, tailwind: true, scss: false })

Documentation

See the full documentation at maz-ui.com/ecosystem/stylelint-config.

Compatibility

• Stylelint >=16 <18
• Node.js >=20.19.0