Introduce text linting of our documentation

.textlintignore

@@ -0,0 +1,20 @@
+CHANGELOG.md
+*/*/CHANGELOG.md
+*/*/LICENSE.md
+LICENSE.md
+build
+*/*/build/*
+*/*/dist/*
+apps/demo/build/**
+apps/storybook/build/**
+docs/**
+examples/**
+exporters/**
+packages/**/dist/**
+packages/design-tokens/**
+packages/exporters/**
+packages/form-validations/**
+packages/icons/**
+packages/web/**
+packages/web-react/**
+packages/web-twig/**

.textlintrc.js

@@ -0,0 +1,18 @@
+module.exports = {
+  rules: {
+    '@lmc-eu/textlint-rule-preset-lmc': {
+      'title-case': {
+        headingLevels: [6],
+        exclude: [
+          '@lmc-eu',
+          '@lmc-eu/spirit-icons',
+          'jest-config-spirit',
+          'prettier-config-spirit',
+        ],
+      },
+      'stop-words': {
+        severity: 'warning',
+      },
+    },
+  },
+};

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Spirit Design System
 
-First of all, thanks for your contribution to this project! ❤️
+Thanks for your contribution to this project! ❤️
 Here are some tips how to make your contributing efforts efficient and eventually accepted & merged:
 
 - [General Usage](#general-usage)
@@ -31,7 +31,7 @@ See [Developer Handbook][developer-handbook] for more information about developm
 
 ## Commit Conventions
 
-All commits you make SHOULD adhere to our commit guidelines. We use [conventional commits][conventional-commits] strategy with a slight modification of our own - [@lmc-eu/commitlint-config][commitlint-config]. This is later used during the release phase to determine how to bump the packages' version numbers based on commit history. 🚀
+All commits you make SHOULD adhere to our commit guidelines. We use [conventional commits][conventional-commits] strategy with a slight modification of our own - [@lmc-eu/commitlint-config][commitlint-config]. This is later used during the release phase to determine how to bump the packages’ version numbers based on commit history. 🚀
 
 ### Commit Message Format
 
@@ -74,7 +74,7 @@ The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` field is opti
 
 MUST be one of the following:
 
-- **Chore**: Changes to our CI configuration files and scripts (examples: CircleCI, SauceLabs) or changes that affect the build system
+- **Chore**: Changes to our CI configuration files and scripts (examples: CircleCI, SauceLabs) or changes that affect the build tool
 - **Deps**: Changes to dependencies
 - **Docs**: Documentation only changes
 - **Feat**: A new feature
@@ -109,7 +109,7 @@ The following is the list of supported scopes:
 - Repository-wide:
   - `ci`: used for changes that affect the Continuous Integration process and builds
   - `repo`: used for repository-wide changes
-  - none/empty string: useful for `Test` and `Refactor` changes that are done across all packages (e.g. `Test: Add missing unit tests`) and for docs changes that are not related to a specific package (e.g. `Docs: Fix typo in the tutorial`).
+  - none/empty string: useful for `Test` and `Refactor` changes that are done across all packages (for example `Test: Add missing unit tests`) and for docs changes that are not related to a specific package (for example `Docs: Fix typo in the tutorial`).
 
 ##### Summary
 
@@ -124,7 +124,7 @@ Use the summary field to provide a succinct description of the change:
 Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
 
 Explain the motivation for the change in the commit message body. This commit message SHOULD explain _why_ you are making the change.
-You can include a comparison of the previous behavior with the new behavior in order to illustrate the impact of the change.
+You can include a comparison of the previous behavior with the new behavior to illustrate the impact of the change.
 
 #### Commit Message Footer
 
@@ -149,7 +149,7 @@ If the commit reverts a previous commit, it SHOULD begin with `Revert: `, follow
 The content of the commit message body SHOULD contain:
 
 - information about the SHA of the commit being reverted in the following format: `This reverts commit <SHA>`,
-- a clear description of the reason for reverting the commit message.
+- a clear description of why the commit message is being reverted.
 
 ### Before Commit
 
@@ -161,18 +161,18 @@ This project uses Prettier for code formatting. You can run `make format` to for
 
 ## Documenting the Components
 
-1. All components MUST be documented in a `README` file in the root of the component, e.g. `packages/web-react/Accordion/README.md`.
+1. All components MUST be documented in a `README` file in the root of the component, for example `packages/web-react/Accordion/README.md`.
 2. The documentation MUST be written in Markdown.
 3. The documentation MUST contain at least a basic example usage of the component.
 4. For complex components or components with subcomponents, the documentation SHOULD contain examples of individual building blocks as well as an example composition.
 5. Component and subcomponent props MUST be documented in a table.
    1. The table MUST be placed in a section introduced by a headline called `API`.
    2. The table MUST contain the following columns:
-      - `Name` — the name of the prop, e.g. `title`
-      - `Type` — the type of the prop, e.g. `string`, `number`, `bool`, `[horizontal | vertical]`, an existing [dictionary][dictionary], etc.
-      - `Default` — the default value of the prop, e.g. `null` or `—` (em-dash) if there is no default value
+      - `Name` — the name of the prop, for example `title`
+      - `Type` — the type of the prop, for example `string`, `number`, `bool`, `[horizontal | vertical]`, an existing [dictionary][dictionary], etc.
+      - `Default` — the default value of the prop, for example `null` or `—` (em-dash) if there is no default value
       - `Required` — if the prop is required `✓` or not `✕`
-      - `Description` — the description of the prop, e.g. `Title of the accordion`
+      - `Description` — the description of the prop, for example `Title of the accordion`
    3. The props MUST be sorted alphabetically by their name.
 
 ## Testing
@@ -182,15 +182,15 @@ Using this you can test the entire package and verify that all parts of the pack
 
 The testing script includes:
 
-- linting using [ESlint][eslint]
+- linting using [ESLint][eslint]
 - checking format using the [Prettier][prettier]
-- checking types using the [Typescript][typescript] compiler
+- checking types using the [TypeScript][typescript] compiler
 - running unit test using the [Jest][jest]
 
 ### Unit Testing
 
 You can run unit testing via `test:unit` scripts.
-For all available scripts see the package's `package.json` file.
+For all available scripts see the package’s `package.json` file.
 
 ### Manual Testing
 
@@ -225,7 +225,7 @@ We have two test suites and you can find them in the `./tests/e2e` directory:
 
 - `demo-homepages` - tests the homepages of our demo apps.
   - This test is used to verify that the demo apps are working properly and their homepages are not broken.
-- `demo-components-compare` - tests components' pages of our demo apps'.
+- `demo-components-compare` - tests components’ pages of our demo apps’.
   - This test gets the list of components from the file system for each package and then it goes through each component and compares its page in all demo apps.
   - Only one screenshot is taken for each component. If you run the update command, only the last screenshot will be saved.
 
@@ -242,16 +242,16 @@ When the tests fail, there will be a comment in the PR with a link to the report
 You can also find the report URL in the GitHub Actions run under the `Run actions/upload-artifact` section.
 Look for `Artifact download URL: https://github.com/lmc-eu/spirit-design-system/actions/runs/<run-id>/artifacts/<artifact-id>`.
 
-⚠️ Currently we do not deploy the Web Twig package to any environment, so you can only test it locally.
+⚠️ We do not deploy the Web Twig package to any environment, so you can only test it locally.
 
 ### Developing and Testing GitHub Actions
 
 It can be time-consuming and painful to test GitHub Actions.
 First, you have to change the GitHub Actions file locally, push your local code into the GitHub repository, and wait for the result.
 
-To solve this issue, you can use [act][act] CLI tool to test and write the GitHub actions locally.
+To solve this issue, you can use [act][act] command line tool to test and write the GitHub actions locally.
 
-For more, please read the article [How to Run GitHub Actions Locally with the act CLI tool][act-article].
+For more, please read the article [How to Run GitHub Actions Locally with the act command line tool][act-article].
 
 ## Publishing
 

DEPRECATIONS-v2.md

@@ -21,11 +21,11 @@ Introducing deprecations and feature flags to be removed in the version 2 lists.
 
 <!--lint enable heading-capitalization -->
 
-- _spirit-web-twig_ was released as version 2 already. See the [CHANGELOG][twig-changelog] for more details or refer to the [migration guide][twig-migration-v2].
+- _spirit-web-twig_ was released as version 2 already. See the [CHANGELOG][twig-changelog] for more details or check the [migration guide][twig-migration-v2].
 
 ---
 
-Please refer back to this list or reach out to our team if you encounter any issues during migration.
+If you face any problems during migration, please check this list or contact our team for assistance.
 
 [web-deprecations-v2]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/DEPRECATIONS-v2.md
 [web-react-deprecations-v2]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/DEPRECATIONS-v2.md

DEPRECATIONS-v3.md

@@ -17,6 +17,6 @@ Introducing deprecations and feature flags to be removed in the version 3 lists.
 
 ---
 
-Please refer back to this list or reach out to our team if you encounter any issues during migration.
+If you face any problems during migration, please check this list or contact our team for assistance.
 
 [web-twig-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/DEPRECATIONS.md

configs/jest-config-spirit/README.md

@@ -36,8 +36,8 @@ export default config;
 
 ## 🙌 Contributing
 
-We're always looking for contributors to help us fix bugs, build new features,
-or help us improve the project documentation. If you're interested, definitely
+We’re always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you’re interested, definitely
 check out our [Contributing Guide][contributing]! 👀
 
 ## 📝 License

configs/prettier-config-spirit/README.md

@@ -24,8 +24,8 @@ export default prettierConfig;
 
 ## 🙌 Contributing
 
-We're always looking for contributors to help us fix bugs, build new features,
-or help us improve the project documentation. If you're interested, definitely
+We’re always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you’re interested, definitely
 check out our [Contributing Guide][contributing]! 👀
 
 ## 📝 License

configs/stylelint-config-spirit/README.md

@@ -24,8 +24,8 @@ export default stylelintConfig;
 
 ## 🙌 Contributing
 
-We're always looking for contributors to help us fix bugs, build new features,
-or help us improve the project documentation. If you're interested, definitely
+We’re always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you’re interested, definitely
 check out our [Contributing Guide][contributing]! 👀
 
 ## 📝 License

docs/DICTIONARIES.md

@@ -2,8 +2,8 @@
 
 This project uses `dictionaries` to unify props between different components.
 
-- Every dictionary is always a range. E.g. the dictionary Size content Small, Medium, Large.
-- If at least 1 item is used from the dictionary in a component's property, all the others should be used. E.g. if there are button sizes Medium and Large, there should also be the size Small.
+- Every dictionary is always a range. For example the dictionary Size content Small, Medium, Large.
+- If at least 1 item is used from the dictionary in a component’s property, all the others should be used. For example if there are button sizes Medium and Large, there should also be the size Small.
 - A given property is not a dictionary by itself. The property is contained in the dictionary. That is, the Action Primary Default color is contained in the Action Primary dictionary entry.
 - Products can extend their dictionaries.
 

docs/contributtion/development.md

@@ -23,7 +23,7 @@ These include:
 
 ### System Requirements
 
-For you to install all the dependencies in this project and successfully develop it, you'll need to:
+For you to install all the dependencies in this project and successfully develop it, you’ll need to:
 
 - [install Node.js][install-nodejs]
 - [install Yarn][install-yarn]
@@ -45,8 +45,8 @@ This strategy is particularly useful during development and tooling like Lerna
 will pick up on when packages are linked in this way and will automatically
 update versions when publishing new versions of packages.
 
-Next up, you'll most likely want to build all of the package files so that
-things don't fail while you are working on a package.
+Next up, you’ll most likely want to build all of the package files so that
+things don’t fail while you are working on a package.
 To do this, you can run the following command:
 
 ```bash

docs/contributtion/experimental-code.md

@@ -73,32 +73,32 @@ introduced it is marked `false` or "off" by default to ensure backward
 compatibility. A feature flag may be configured in JavaScript, SASS, or both.
 
 All the currently available feature flags, as well as how to enable them, is
-documented in each package's main README file in the section `Feature Flags`.
+documented in each package’s main README file in the section `Feature Flags`.
 
 ### Feature Flag Naming Convention
 
 All feature flags follow a prefix naming convention that indicates status.
 
 #### Flags Prefixed with `enable-*`
 
-- Contain new features that we'd like consuming projects to test
+- Contain new features that we’d like consuming projects to test
 - Are generally stable and unlikely to change but may change based on user
   feedback
 - May require some manual migration or code changes within your project
-- Are documented in the package's main README file
-- Need user feedback to ensure we've met all concerns relating to this feature
+- Are documented in the package’s main README file
+- Need user feedback to ensure we’ve met all concerns relating to this feature
 - Are used for introducing visual changes that are considered breaking
 
-If you use these flags, make sure to check our release notes where we'll outline
+If you use these flags, make sure to check our release notes where we’ll outline
 any changes to them across our releases.
 
 #### Flags Prefixed with `enable-v#-*`
 
 As the usage of an existing flag increases or we determine a feature to be of high
-importance, we'll "commit" it to a future major release and rename it to use the
+importance, we’ll "commit" it to a future major release and rename it to use the
 `enable-v#-*` prefix. At this point, the API or functionality behind this flag is
-now fixed and won't change. We intend to ship this flag as "on by default" in
-the major version indicated in the name. e.g. `enable-v3-some-feature`
+now fixed and won’t change. We intend to ship this flag as "on by default" in
+the major version indicated in the name. for example `enable-v3-some-feature`
 
 All breaking changes will be shipped as `enable-v#-*` flags within the current
 releases. This enables projects to opt-in to breaking changes earlier
@@ -127,19 +127,19 @@ Folders and stories within this section in the Storybook show components with al
 All the currently available feature flags, as well as how to enable them, are documented in the main documentation.
 
 Individual feature flags that are available for some components only will be also documented in
-the component's README file.
+the component’s README file.
 
 ## Expanding Existing APIs
 
 New experimental functionality might sometimes be added with the need for an
 `UNSTABLE_` export or a feature flag. Oftentimes, this ends up being a new prop
 on a component.
-The documentation associated with this prop (TypeScript types, Storybook controls, etc.) will state that it's experimental.
+The documentation associated with this prop (TypeScript types, Storybook controls, etc.) will state that it’s experimental.
 
 ## Moving to Stable
 
 Over time it becomes apparent an experimental API has stabilized and suits the
-needs of most users. If it isn't a breaking change, and there hasn't been much
+needs of most users. If it isn’t a breaking change, and there hasn’t been much
 movement, it can be moved from "experimental" status to "stable".
 
 To initiate a move to stable, a new issue can be opened to request the team to evaluate
@@ -162,18 +162,18 @@ be met to move a component from experimental to stable:
           `onClick = () => {}` can cause re-renders since the function identity
           is not stable
   - [ ] Component has a story in `<ComponentName>.stories.ts`
-    - [ ] The story has an MDX overview that embeds the main component's README file
+    - [ ] The story has an MDX overview that embeds the main component’s README file
     - [ ] MDX document covers at least common component states and provides a prop
           table
     - [ ] Stories cover at least common component states
     - [ ] Stories generate a `Playground` for controls
       - [ ] Controls with no meaningful change to the component visuals should
-            be hidden from the controls panel, eg. `className`
+            be hidden from the controls panel, for example `className`
       - [ ] Props of type `node` with no proper controls available for
             configuration should be hidden from the controls panel, eg.
             `children`
     - [ ] Stories should mirror the intended usage of the component
-  - [ ] The component has unit/integration/snapshot tests written using the project's unit testing library for testing the component API
-  - [ ] The component has visual tests written using the project's End-to-End testing library for testing the component design
+  - [ ] The component has unit/integration/snapshot tests written using the project’s unit testing library for testing the component API
+  - [ ] The component has visual tests written using the project’s End-to-End testing library for testing the component design
 
 [docs-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/contributtion/feature-flags.md

docs/contributtion/feature-flags.md

@@ -15,10 +15,10 @@ Folders and stories within this section in Storybook show components with all fe
 
 ## Current Feature Flags
 
-Feature flags prefixed with `enable-*` contain features we'd like consuming projects to
+Feature flags prefixed with `enable-*` contain features we’d like consuming projects to
 test and give us feedback on. It will be made by default in the version specified in the name.
 In most of the cases these features will be breaking changes - logically or visually.
-They're generally stable and unlikely to change but may change based on your feedback.
+They’re generally stable and unlikely to change but may change based on your feedback.
 We just do not want to break your application or design without your consent.
 
 Flags prefixed with `enable-v#-*` will be removed in the next major version and their behavior will be made the default.
@@ -49,7 +49,7 @@ Example with fictional feature flag to enable fullscreen modal:
 ```
 
 Every feature flag should also provide a class selector that can be used to enable or disable the feature.
-You can use this class if you want to limit the usage of the feature to a specific part of your application.
+You can use this class to limit the usage of the feature to a specific part of your application.
 Place the class on any parent element of the component you want to enable the feature for.
 
 Example: