@taiga-ui/stylelint-config 0.521.0 → 0.523.0

package/README.md

@@ -1,22 +1,64 @@
 # @taiga-ui/stylelint-config
 
-Common Stylelint configuration for taiga-ui projects
+Common Stylelint configuration for Taiga UI projects.
 
-## Usage
+```bash
+npm i -D stylelint @taiga-ui/stylelint-config
+```
 
-1. Install from npm
+`stylelint.config.mjs`
 
-```bash
-npm i --save-dev @taiga-ui/stylelint-config
+**Attention**: package does not support CommonJS, use `stylelint.config.mjs` or `stylelint.config.js` in a module
+package instead of `stylelint.config.cjs`.
+
+```js
+export default {
+  extends: ['@taiga-ui/stylelint-config'],
+};
 ```
 
-2. Create `stylelint.config.js` at project root
+Taiga UI projects can also add the stricter package-specific config:
 
-```json5
-{
-  extends: ['@taiga-ui/stylelint-config/taiga'],
-}
+```js
+export default {
+  extends: ['@taiga-ui/stylelint-config', '@taiga-ui/stylelint-config/taiga-specific'],
+};
 ```
 
-More information about available at
-[stylelint documentation](https://github.com/stylelint/stylelint/blob/main/docs/user-guide/configure.md)
+## Configs
+
+| Config           | Entry point                                 | Description                                      |
+| ---------------- | ------------------------------------------- | ------------------------------------------------ |
+| `recommended`    | `@taiga-ui/stylelint-config`                | Common CSS, Less, compatibility, and style rules |
+| `taiga-specific` | `@taiga-ui/stylelint-config/taiga-specific` | Taiga UI custom property naming                  |
+
+## Recommended config contents
+
+The root entry point combines Taiga UI custom rules with external Stylelint presets and plugins. The exact options live
+in
+[`configs/recommended.ts`](https://github.com/taiga-family/toolkit/blob/main/projects/stylelint-config/configs/recommended.ts).
+
+| Package                                                                                                         | What is included in `recommended`               |
+| --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| [Stylelint core](https://stylelint.io/user-guide/rules)                                                         | Individual CSS correctness and formatting rules |
+| [@stylistic/stylelint-config](https://github.com/stylelint-stylistic/stylelint-stylistic)                       | Base stylistic preset                           |
+| [@stylistic/stylelint-plugin](https://github.com/stylelint-stylistic/stylelint-stylistic)                       | Individual stylistic rule overrides             |
+| [stylelint-plugin-logical-css](https://github.com/yuschick/stylelint-plugin-logical-css)                        | Logical property and keyword rules              |
+| [stylelint-use-logical](https://github.com/csstools/stylelint-use-logical)                                      | Logical CSS migration rules                     |
+| [stylelint-order](https://github.com/hudochenkov/stylelint-order)                                               | Property ordering                               |
+| [stylelint-rem-over-px](https://github.com/a-tarasyuk/stylelint-rem-over-px)                                    | Prefer `rem` values over most `px` values       |
+| [stylelint-plugin-use-baseline](https://github.com/ryo-manba/stylelint-plugin-use-baseline)                     | Baseline browser feature checks                 |
+| [stylelint-no-unsupported-browser-features](https://github.com/ismay/stylelint-no-unsupported-browser-features) | Browserslist compatibility checks               |
+| Taiga UI custom rules                                                                                           | Project-specific rules listed below             |
+
+- ✅ = recommended
+- 🔧 = fixable
+
+| Rule                                                                                                                                                   | Description                                                               | ✅  | 🔧  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | --- | --- |
+| [no-mask-shorthand](https://github.com/taiga-family/toolkit/tree/main/projects/stylelint-config/docs/no-mask-shorthand.md)                             | Expands `mask` shorthand declarations into explicit longhand declarations | ✅  | 🔧  |
+| [no-webkit-box-orient-block-axis](https://github.com/taiga-family/toolkit/tree/main/projects/stylelint-config/docs/no-webkit-box-orient-block-axis.md) | Replaces `-webkit-box-orient: block-axis` with `vertical`                 | ✅  | 🔧  |
+| [relative-less-import-extension](https://github.com/taiga-family/toolkit/tree/main/projects/stylelint-config/docs/relative-less-import-extension.md)   | Adds an explicit extension to relative stylesheet imports                 | ✅  | 🔧  |
+
+More information about configuring Stylelint is available in the
+[Stylelint documentation](https://stylelint.io/user-guide/configure).

package/configs/recommended.d.ts

@@ -0,0 +1,6 @@
+import { type Config } from 'stylelint';
+type StylelintConfig = Config & {
+    readonly $schema: string;
+};
+declare const config: StylelintConfig;
+export default config;

package/configs/taiga-specific.d.ts

@@ -0,0 +1,6 @@
+import { type Config } from 'stylelint';
+type StylelintConfig = Config & {
+    readonly $schema: string;
+};
+declare const config: StylelintConfig;
+export default config;

package/docs/no-mask-shorthand.md

@@ -0,0 +1,28 @@
+# no-mask-shorthand
+
+<sup>`✅ Recommended`</sup> <sup>`Fixable`</sup>
+
+> ✅ Included in `recommended`.
+
+Disallows the `mask` shorthand and expands it into explicit `mask-*` longhand declarations. This keeps resets visible,
+avoids accidental changes to unrelated mask longhands, and makes review diffs easier to read. Autofix is skipped for
+CSS-wide keywords, CSS variables, and values the rule cannot safely classify.
+
+```css
+/* ❌ error */
+.icon {
+  mask: url('icon.svg') no-repeat center / 1rem;
+}
+
+/* ✅ after autofix */
+.icon {
+  mask-image: url('icon.svg');
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: 1rem;
+}
+```
+
+## Options
+
+This rule has no options.

package/docs/no-webkit-box-orient-block-axis.md

@@ -0,0 +1,25 @@
+# no-webkit-box-orient-block-axis
+
+<sup>`✅ Recommended`</sup> <sup>`Fixable`</sup>
+
+> ✅ Included in `recommended`.
+
+Disallows `-webkit-box-orient: block-axis` and replaces it with `-webkit-box-orient: vertical`. Legacy WebKit line
+clamping depends on the physical `vertical` value, so the logical `block-axis` value can break truncation in browsers
+that still rely on this property.
+
+```css
+/* ❌ error */
+.title {
+  -webkit-box-orient: block-axis;
+}
+
+/* ✅ after autofix */
+.title {
+  -webkit-box-orient: vertical;
+}
+```
+
+## Options
+
+This rule has no options.

package/docs/relative-less-import-extension.md

@@ -0,0 +1,21 @@
+# relative-less-import-extension
+
+<sup>`✅ Recommended`</sup> <sup>`Fixable`</sup>
+
+> ✅ Included in `recommended`.
+
+Requires relative stylesheet imports to include an explicit file extension. The autofix uses the current file extension
+when it is `.less`, `.scss`, or `.css`, and falls back to `.less` otherwise. Package imports, absolute imports, URLs,
+data URLs, and paths that already include a style extension are ignored.
+
+```css
+/* ❌ error */
+@import './tokens';
+
+/* ✅ after autofix */
+@import './tokens.less';
+```
+
+## Options
+
+This rule has no options.

package/index.d.ts

@@ -1,6 +1 @@
-import { type Config } from 'stylelint';
-type StylelintConfig = Config & {
-    readonly $schema: string;
-};
-declare const config: StylelintConfig;
-export = config;
+export { default } from './configs/recommended';