From 899bd3739bc34438883db39349f6875ffc8a27d5 Mon Sep 17 00:00:00 2001
From: literat <tomas@litera.me>
Date: Wed, 21 Aug 2024 11:56:05 +0200
Subject: [PATCH] Docs(stylelint-config): Add recommended configuration,
 ordering and stylistic rules

---
 packages/stylelint-config/README.md | 95 ++++++++++++++++++++++++++---
 1 file changed, 87 insertions(+), 8 deletions(-)

diff --git a/packages/stylelint-config/README.md b/packages/stylelint-config/README.md
index ce8af92..1bc69d6 100644
--- a/packages/stylelint-config/README.md
+++ b/packages/stylelint-config/README.md
@@ -4,20 +4,20 @@
 [![Node version](https://img.shields.io/node/v/@almacareer/stylelint-config.svg?style=flat&logo=nodedotjs)](http://nodejs.org/download/)
 [![Stylelint version](https://img.shields.io/npm/dependency-version/@almacareer/stylelint-config/peer/stylelint?logo=stylelint)](https://github.com/stylelint/stylelint)
 
-> LMC’s config for Stylelint
+> Alma Career’s config for Stylelint
 
 ## Usage
 
 ```bash
 # Yarn:
-yarn add --dev @almacareer/stylelint-config stylelint-config-prettier
+yarn add --dev @almacareer/stylelint-config stylelint-prettier
 
 # npm:
-npm install --save-dev @almacareer/stylelint-config stylelint-config-prettier
+npm install --save-dev @almacareer/stylelint-config stylelint-prettier
 ```
 
 > We assume you are using Prettier. That’s why we also recommend adding
-> `stylelint-config-prettier` above.
+> `stylelint-prettier` above.
 
 Configuration extends community maintained config [stylelint-config-standard-scss](https://github.com/stylelint-scss/stylelint-config-standard-scss).
 
@@ -39,7 +39,7 @@ Use this ruleset to configure Stylelint to work with your code.
 // .stylelintrc.mjs
 
 export default {
-  extends: ['@almacareer/stylelint-config', 'stylelint-config-prettier'],
+  extends: ['@almacareer/stylelint-config', 'stylelint-prettier/recommended'],
 };
 ```
 
@@ -48,7 +48,7 @@ export default {
 
 ```json
 {
-  "extends": ["@almacareer/stylelint-config", "stylelint-config-prettier"]
+  "extends": ["@almacareer/stylelint-config", "stylelint-prettier/recommended"]
 }
 ```
 
@@ -60,11 +60,90 @@ export default {
 ```json
 {
   "stylelint": {
-    "extends": ["@almacareer/stylelint-config", "stylelint-config-prettier"]
+    "extends": ["@almacareer/stylelint-config", "stylelint-prettier/recommended"]
   }
 }
 ```
 
 </details>
 
----
+## Checking Properties Order
+
+To further extend control over coding style of your stylesheets, we are also
+checking for properties order.
+
+The `order` config enforces a consistent order of content in your declaration blocks:
+
+1. SASS variables,
+2. CSS custom properties,
+3. SASS `@extend`,
+4. single-line SASS `@include`,
+5. declarations,
+6. nested rules,
+
+For better flexibility, block at-rules (like `@media`, `@supports`, and also Sass `@if`, `@each`, etc.) can be placed
+anywhere in the declaration block.
+
+Besides, properties in the declarations must be ordered by following categories:
+
+1. `all` properties,
+2. `content`,
+3. position,
+4. `appearance`,
+5. box model,
+6. typography,
+7. decorations,
+8. effects and transforms,
+9. interactions,
+10. transitions and animations.
+
+👉 To see the order of individual properties this config prescribes, please read
+the [`order` config itself](./rules/order.js).
+
+## Stylistic Rules
+
+Stylistic rules (like indentation etc.) [were dropped][stylelint-v16-stylistic-rules]
+in Stylelint v16. To enforce them, you can use
+[`stylelint-prettier`][stylelint-prettier]:
+
+```json
+// `.stylelintrc`
+{
+  "plugins": ["stylelint-prettier"],
+  "rules": {
+    "prettier/prettier": true
+  }
+}
+```
+
+Or, if you feel brave enough and don’t need granular configuration of the stylistic rules,
+you can use [Prettier].
+
+## FAQ
+
+<details>
+<summary>How do I change the indentation?</summary>
+### With Prettier
+
+If using Prettier, you can configure the indentation in your Prettier config:
+
+```json
+{
+  "tabWidth": 2
+}
+```
+
+Or in your [`.editorconfig`][editorconfig]:
+
+```ini
+[*]
+indent_size = 2
+```
+
+👉 See [Prettier][prettier] documentation for more options.
+
+</details>
+
+[prettier]: https://prettier.io
+[stylelint-v16-stylistic-rules]: https://stylelint.io/migration-guide/to-16/#removed-deprecated-stylistic-rules
+[stylelint-prettier]: https://github.com/prettier/stylelint-prettier