@kununu/stylelint-config/README.md

kununu's stylelint config

# @kununu/stylelint-config

> kununu style linter configuration

Shared [stylelint](https://stylelint.io/) configuration for kununu's SCSS, used
across the frontend apps and `@kununu/ui`. It builds on
[`stylelint-config-standard-scss`](https://github.com/stylelint-scss/stylelint-config-standard-scss)
and enforces kununu's conventions plus Prettier formatting.

`stylelint` itself is bundled as a dependency, so you don't need to install it
separately. The package pins Node `24.13.1` / npm `11.8.0` in `engines`.

## 📦 Installation

Add the package as a dev dependency:

```console
npm install @kununu/stylelint-config --save-dev
```

## 💻 Usage

Create a `.stylelintrc` (or `.stylelintrc.json`) file:

```json
{
  "extends": "@kununu/stylelint-config"
}
```

Add a lint script targeting your SCSS files to `package.json`:

```json
{
  "scripts": {
    "lint": "stylelint '**/*.scss'"
  }
}
```

See the [stylelint docs](https://stylelint.io/user-guide/configuration) for more
detailed configuration options.

## 🎨 What's included

The config extends `stylelint-config-standard-scss` and
`stylelint-prettier/recommended`, then layers on kununu's conventions. The
notable rules:

- **Class selectors** must be **camelCase** (`selector-class-pattern`).
- **SCSS mixin names** must be **kebab-case** (`scss/at-mixin-pattern`).
- **Colors:** named colors are forbidden (`color-named`), hex must be long form
  (`#ffffff`, not `#fff`), and legacy color/alpha notation is used
  (`rgba(0, 0, 0, 0.5)`).
- **No duplicate selectors**, and ID selectors are flagged as a **warning**
  (not an error).
- CSS Modules pseudo-selectors (`:export`, `:global`, `:local`, `:import`) are
  allowed.
- **Property and selector ordering** is enforced via
  [`stylelint-semantic-groups`](https://www.npmjs.com/package/stylelint-semantic-groups).

### Formatting (Prettier)

Formatting is handled by [Prettier](https://prettier.io/) through
`stylelint-prettier` and reported as lint errors (auto-fixable with
`stylelint --fix`). The relevant options are pinned here:

| Option | Value |
| --- | --- |
| `printWidth` | `80` |
| `tabWidth` | `2` |
| `useTabs` | `false` |
| `singleQuote` | `true` |
| `trailingComma` | `'all'` |

> **Note:** these Prettier options are enforced by this config and
> **intentionally override any `.prettierrc` in the consuming project** for SCSS
> files. This keeps SCSS formatting consistent across all repos regardless of
> each project's JS/TS Prettier setup.

## ⚡️ Editor integration

Linting runs in CI (and pre-commit, where configured), but catching errors in
your editor is faster. We recommend the
[stylelint VS Code extension](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint).

Installing the extension alone often isn't enough to lint SCSS — add this to
your `.vscode/settings.json` so it validates SCSS and stylelint owns formatting
instead of the built-in linters:

```json
{
  "stylelint.validate": ["css", "scss"],
  "css.validate": false,
  "scss.validate": false
}
```