From cf6b2ac964a50e0ef25f4a2cb343be2ce3c6deac Mon Sep 17 00:00:00 2001 From: literat Date: Thu, 22 Aug 2024 17:46:34 +0200 Subject: [PATCH] Style(repo): Fix documentation content according to the textlint rules --- CONTRIBUTING.md | 36 +++++++++++----------- DEPRECATIONS-v2.md | 4 +-- DEPRECATIONS-v3.md | 2 +- configs/jest-config-spirit/README.md | 4 +-- configs/prettier-config-spirit/README.md | 4 +-- configs/stylelint-config-spirit/README.md | 4 +-- docs/DICTIONARIES.md | 4 +-- docs/contributtion/development.md | 6 ++-- docs/contributtion/experimental-code.md | 30 +++++++++--------- docs/contributtion/feature-flags.md | 6 ++-- docs/decisions/001-custom-design-system.md | 4 +-- docs/decisions/002-node-version.md | 4 +-- docs/decisions/003-typescript-only.md | 4 +-- docs/decisions/006-experimental-code.md | 4 +-- docs/decisions/007-release-names.md | 6 ++-- docs/decisions/README.md | 6 ++-- docs/migrations/web-react/MIGRATION-v1.md | 6 ++-- docs/migrations/web-react/MIGRATION-v2.md | 14 ++++----- docs/migrations/web-twig/MIGRATION-v2.md | 4 +-- docs/migrations/web-twig/MIGRATION-v3.md | 12 ++++---- docs/migrations/web/MIGRATION-v1.md | 6 ++-- docs/migrations/web/MIGRATION-v2.md | 12 ++++---- examples/next-with-app-router/README.md | 2 +- examples/next-with-pages-router/README.md | 2 +- exporters/svg/README.md | 2 +- packages/analytics/README.md | 4 +-- packages/codemods/README.md | 2 +- packages/design-tokens/README.md | 34 ++++++++++---------- packages/form-validations/README.md | 4 +-- packages/icons/README.md | 4 +-- 30 files changed, 118 insertions(+), 118 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 53c50dc75e..9017657562 100644 --- a/CONTRIBUTING.md +++ b/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 `` and `` fields are mandatory, the `()` 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 `, -- 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//artifacts/`. -⚠️ 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 diff --git a/DEPRECATIONS-v2.md b/DEPRECATIONS-v2.md index 3895ff41b9..3b1c532f32 100644 --- a/DEPRECATIONS-v2.md +++ b/DEPRECATIONS-v2.md @@ -21,11 +21,11 @@ Introducing deprecations and feature flags to be removed in the version 2 lists. -- _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 diff --git a/DEPRECATIONS-v3.md b/DEPRECATIONS-v3.md index d1f7d82a87..797cb31b6f 100644 --- a/DEPRECATIONS-v3.md +++ b/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 diff --git a/configs/jest-config-spirit/README.md b/configs/jest-config-spirit/README.md index e9f8281970..9905f969c2 100644 --- a/configs/jest-config-spirit/README.md +++ b/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 diff --git a/configs/prettier-config-spirit/README.md b/configs/prettier-config-spirit/README.md index 2866daac57..712a9895df 100644 --- a/configs/prettier-config-spirit/README.md +++ b/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 diff --git a/configs/stylelint-config-spirit/README.md b/configs/stylelint-config-spirit/README.md index e43207c14c..d8fa77a9b6 100644 --- a/configs/stylelint-config-spirit/README.md +++ b/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 diff --git a/docs/DICTIONARIES.md b/docs/DICTIONARIES.md index 1fb7f5349a..a801e42731 100644 --- a/docs/DICTIONARIES.md +++ b/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. diff --git a/docs/contributtion/development.md b/docs/contributtion/development.md index 90463470cf..4c8bbf2c06 100644 --- a/docs/contributtion/development.md +++ b/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 diff --git a/docs/contributtion/experimental-code.md b/docs/contributtion/experimental-code.md index 446cd70ed7..0d34859292 100644 --- a/docs/contributtion/experimental-code.md +++ b/docs/contributtion/experimental-code.md @@ -73,7 +73,7 @@ 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 @@ -81,24 +81,24 @@ 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 `.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 diff --git a/docs/contributtion/feature-flags.md b/docs/contributtion/feature-flags.md index 6812888d9d..27320e713c 100644 --- a/docs/contributtion/feature-flags.md +++ b/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: diff --git a/docs/decisions/001-custom-design-system.md b/docs/decisions/001-custom-design-system.md index 3bc6786e22..be7062d8b1 100644 --- a/docs/decisions/001-custom-design-system.md +++ b/docs/decisions/001-custom-design-system.md @@ -15,9 +15,9 @@ Here are the arguments that we still see as important so far: - A dedicated team keeps the know-how in-house. They know and pass on how to build a quality database, how to share code and design across teams, how to write documentation, how to automatically manage styles, etc. - We release new versions and patches when we need them. -- There is currently no design system that supports all the necessary technologies at once ([Sass][sass], [React][react], [Twig][twig]), so we would have to extend a ready-made one anyway +- There is currently no design system that supports all the necessary technologies at once ([SASS][sass], [React][react], [Twig][twig]), so we would have to extend a ready-made one anyway - We use the design system to set design boundaries and direction. - We don't want the design system to support every possible feature (as opposed to [Material UI][mui]), but we do want it to set design boundaries while maintaining product consistency. + We don’t want the design system to support every possible feature (as opposed to [Material UI][mui]), but we do want it to set design boundaries while maintaining product consistency. Another competitor in this field is [Bootstrap][bootstrap], which was hard to bend into a multi-brand architecture, so we built on it at first but then abandoned it. diff --git a/docs/decisions/002-node-version.md b/docs/decisions/002-node-version.md index 2470d5224f..5e63022e15 100644 --- a/docs/decisions/002-node-version.md +++ b/docs/decisions/002-node-version.md @@ -25,9 +25,9 @@ Support the minimal Node.js version which is used by our adopters. ## Consequences -Folks should hopefully run into a few compatibility issues. They may need features that are not back-ported to the current active LTS version, however, it's trivial to update the Node.js version. +Folks should hopefully run into a few compatibility issues. They may need features that are not back-ported to the current active LTS version, however, it’s trivial to update the Node.js version. -We'll need to update the Node.js version in the packages whenever the active LTS +We’ll need to update the Node.js version in the packages whenever the active LTS version changes. [node-releases]: https://nodejs.org/en/about/releases/ diff --git a/docs/decisions/003-typescript-only.md b/docs/decisions/003-typescript-only.md index 0e9fe2abbe..04f0d5df13 100644 --- a/docs/decisions/003-typescript-only.md +++ b/docs/decisions/003-typescript-only.md @@ -20,13 +20,13 @@ This is increasingly becoming less of an issue with more and more dependencies b We strongly advise the use of [TypeScript][typescript] even for simple projects and those worked on by single developers. -This project uses and leverages Typescript in every possible way to have the best developer experience. +This project uses and leverages TypeScript in every possible way to have the best developer experience. ## Consequences This makes the initial experience not great for folks using JavaScript. -This also may anger some folks who really don't like [TypeScript][typescript]. +This also may anger some folks who really don’t like [TypeScript][typescript]. For those folks, we provide also transpiled packages that can be used in a JavaScript environment. [typescript]: https://www.typescriptlang.org/ diff --git a/docs/decisions/006-experimental-code.md b/docs/decisions/006-experimental-code.md index 949c8e3bfa..5187b98a34 100644 --- a/docs/decisions/006-experimental-code.md +++ b/docs/decisions/006-experimental-code.md @@ -30,12 +30,12 @@ Oftentimes this ends up being a new prop on a component. For teams using these features, they will need to import the functionality by using the `UNSTABLE_` prefix. -The documentation associated with experimental prop (TypeScript types, Storybook controls, etc.) will state that it's experimental, mainly in th component README. +The documentation associated with experimental prop (TypeScript types, Storybook controls, etc.) will state that it’s experimental, mainly in th component README. The API is not fixed and is likely to change. The API is not bound by semver. The component, export, feature, etc. may change, be renamed, or removed in the future without warning. -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 movement, it can be moved from "experimental" status 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 movement, it can be moved from "experimental" status to "stable". Note: Details on how to document experimental components and exports prefixed with `UNSTABLE_` can be found in the [documentation][docs-experimental-code]. diff --git a/docs/decisions/007-release-names.md b/docs/decisions/007-release-names.md index ffbc6c30fe..485b559145 100644 --- a/docs/decisions/007-release-names.md +++ b/docs/decisions/007-release-names.md @@ -10,8 +10,8 @@ In our design system, we have been using semantic versioning for individual pack We have been also talking about the version of the entire design system like we have v1 and v2. In the beginning, this was fine, as the individual packages were mostly updated together and the major versions were the same. But as the entire system evolved, we started to have different versions for different packages. -We've found that this can lead to confusion about the state of the entire system, as different packages can be at different versions. -To address this, we've decided to introduce a global version of the entire design system, which we're calling a "distribution" or "edition". +We’ve found that this can lead to confusion about the state of the entire system, as different packages can be at different versions. +To address this, we’ve decided to introduce a global version of the entire design system, which we’re calling a "distribution" or "edition". Each distribution will also have a unique name to make it easier to refer to specific releases. ## Decision @@ -24,7 +24,7 @@ This version name will be updated on every major release, regardless of which pa This will give us a single version name that represents the state of the entire system. Each distribution of the design system will thus have a unique name. -We've chosen a list of names that we will use for future distributions. +We’ve chosen a list of names that we will use for future distributions. List of Distribution Names: diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 010cd0c648..6bb30f7a6b 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -1,12 +1,12 @@ # Decisions -## I've been around. +## I’ve been around. -### And I've got opinions... +### And I’ve got opinions... ![][opinions-image] -This directory contains all the decisions we've made for this design system as a record for whenever we wonder why certain decisions were made. +This directory contains all the decisions we’ve made for this design system as a record for whenever we wonder why certain decisions were made. Decisions here are never final. But these documents should serve as a good way for someone to come up to speed on why certain decisions were made. diff --git a/docs/migrations/web-react/MIGRATION-v1.md b/docs/migrations/web-react/MIGRATION-v1.md index 9330109859..ae9e35b874 100644 --- a/docs/migrations/web-react/MIGRATION-v1.md +++ b/docs/migrations/web-react/MIGRATION-v1.md @@ -43,7 +43,7 @@ Rename and use `Checkbox` component instead of `CheckboxField`. - Instead of the `message` prop, use `validationText`. - The `validationState` prop is now required when using `validationText`. - If `validationState` is not set, `validationText` won't render. + If `validationState` is not set, `validationText` won’t render. - To show a permanent helper, use `helperText`. - `<… validationState="danger" message="error" …>` → `<… validationState="danger" validationText="error" …>` @@ -67,7 +67,7 @@ The most notable change is that the mobile and desktop navigation are now separa - `HeaderDialog` Formerly, the desktop dialog (holding the site navigation) was a responsive CSS modification of a shared HTML code. -With the new `Header` and `HeaderDialog`, each component has its own instance of the navigation, i.e. the navigation code is duplicated. +With the new `Header` and `HeaderDialog`, each component has its own instance of the navigation, that is the navigation code is duplicated. This is because `HeaderDialog` will become an independent component in the future. You may need to take additional measures so your SEO is not affected by the duplicate HTML code of the navigation. @@ -93,7 +93,7 @@ If you need the `Stack` to have a spacing, add `hasSpacing` prop. By default, `S - `` → `` -If you already used the feature class, you can remove it and don't need to do any other changes. +If you already used the feature class, you can remove it and don’t need to do any other changes. ## Remove `theme` and `tag` props and `default` color from `Tag` [#DS-648](https://jira.lmc.cz/browse/DS-648) ([f2f26eb](https://github.com/lmc-eu/spirit-design-system/commit/f2f26eb)) diff --git a/docs/migrations/web-react/MIGRATION-v2.md b/docs/migrations/web-react/MIGRATION-v2.md index 2d7eb939ee..9ba8f16539 100644 --- a/docs/migrations/web-react/MIGRATION-v2.md +++ b/docs/migrations/web-react/MIGRATION-v2.md @@ -4,7 +4,7 @@ Introducing version 2 of the _spirit-web-react_ package. > Please follow these steps to safely upgrade to Spirit Design System v2 components. -> ℹ️ Don't forget to check the [migration guide of the _spirit-web_ package][migration-guide-web] for general changes in +> ℹ️ Don’t forget to check the [migration guide of the _spirit-web_ package][migration-guide-web] for general changes in > available feature flags, CSS, and other changes that might affect your project. ## Overview @@ -89,7 +89,7 @@ The `danger` icon for `danger` color in the Alert component is now required. #### Migration Guide -Either install newer version of the _spirit-icons_ package, or add an icon named `danger` to your project's icons. +Either install newer version of the _spirit-icons_ package, or add an icon named `danger` to your project’s icons. ### Alert: `role="alert"` @@ -99,13 +99,13 @@ As explained in the [ARIA: alert role][alert-role-documentation] documentation: > The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is > added to an element, the browser will send out an accessible alert event to assistive technology products which can -> then notify the user. The alert role should only be used for information that requires the user's immediate attention, +> then notify the user. The alert role should only be used for information that requires the user’s immediate attention, > which is typically content that is dynamically displayed (such as form validation message etc.), not for content that -> appears on page load. It should not be used on HTML that the user hasn't interacted with. +> appears on page load. It should not be used on HTML that the user hasn’t interacted with. #### Migration Guide -In case you need to use the component as an information that requires the user's immediate attention, you can use +In case you need to use the component as an information that requires the user’s immediate attention, you can use `role="alert"` as an [additional attribute][readme-additional-attributes]. ### Collapse: `id` Prop @@ -450,7 +450,7 @@ The `label` prop is now required by the TextField component. #### Migration Guide Please ensure that `label` is added to all instances of the TextField component. -If you need to hide the `label`, you can use the `isLabelHidden` prop. +To hide the `label`, you can use the `isLabelHidden` prop. ### Tooltip: `off` Placement @@ -469,7 +469,7 @@ wrapping component. Similarly, Tooltip (the tip itself) was renamed to TooltipPo 👉 See [Tooltip documentation][tooltip-readme] for more details and examples. -Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That's because we found out that most +Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That’s because we found out that most users want the advanced positioning options anyway. Instead of: diff --git a/docs/migrations/web-twig/MIGRATION-v2.md b/docs/migrations/web-twig/MIGRATION-v2.md index f282d4db24..fcf56196c7 100644 --- a/docs/migrations/web-twig/MIGRATION-v2.md +++ b/docs/migrations/web-twig/MIGRATION-v2.md @@ -161,7 +161,7 @@ If you need the `Stack` to have a spacing, add `hasSpacing` prop. By default, `S - `` → `` -If you already used the feature class, you can remove it and don't need to do any other changes. +If you already used the feature class, you can remove it and don’t need to do any other changes. ## Remove `onClick` prop [#DS-686](https://jira.lmc.cz/browse/DS-686) ([836e826](https://github.com/lmc-eu/spirit-design-system/commit/836e826)) @@ -193,7 +193,7 @@ Instead of the `size` prop, use `boxSize` in `Icon` component. - Instead of the `message` prop, use `validationText`. - The `validationState` prop is now required when using `validationText`. - If `validationState` is not set, `validationText` won't render. + If `validationState` is not set, `validationText` won’t render. - To show a permanent helper, use `helperText`. ### Other Notable Changes diff --git a/docs/migrations/web-twig/MIGRATION-v3.md b/docs/migrations/web-twig/MIGRATION-v3.md index 3dd632949e..d5e0fd74bd 100644 --- a/docs/migrations/web-twig/MIGRATION-v3.md +++ b/docs/migrations/web-twig/MIGRATION-v3.md @@ -4,7 +4,7 @@ Introducing version 3 of the _spirit-web-twig_ package. > Please follow these steps to safely upgrade to Spirit Design System v3 components. -> ℹ️ Don't forget to check the [migration guide of the _spirit-web_ package][migration-guide-web] for general changes in +> ℹ️ Don’t forget to check the [migration guide of the _spirit-web_ package][migration-guide-web] for general changes in > available feature flags, CSS, JavaScript plugins, and other changes that might affect your project. ## Overview @@ -77,7 +77,7 @@ The `danger` icon for `danger` color in the Alert component is now required. #### Migration Guide -Either install newer version of the _spirit-icons_ package, or add an icon named `danger` to your project's icons. +Either install newer version of the _spirit-icons_ package, or add an icon named `danger` to your project’s icons. ### Alert: `role="alert"` @@ -87,13 +87,13 @@ As explained in the [ARIA: alert role][alert-role-documentation] documentation: > The alert role is used to communicate an important and usually time-sensitive message to the user. When this role is > added to an element, the browser will send out an accessible alert event to assistive technology products which can -> then notify the user. The alert role should only be used for information that requires the user's immediate attention, +> then notify the user. The alert role should only be used for information that requires the user’s immediate attention, > which is typically content that is dynamically displayed (such as form validation message etc.), not for content that -> appears on page load. It should not be used on HTML that the user hasn't interacted with. +> appears on page load. It should not be used on HTML that the user hasn’t interacted with. #### Migration Guide -In case you need to use the component as an information that requires the user's immediate attention, you can use +In case you need to use the component as an information that requires the user’s immediate attention, you can use `role="alert"` as an [additional attribute][readme-additional-attributes]. ### Breadcrumbs: `goBackTitle` Prop @@ -382,7 +382,7 @@ Update cross-axis names in the placement prop: ### Tooltip: TooltipPopover `enableControlledPlacement` Prop -Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That's because we found out that +Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That’s because we found out that most users want the advanced positioning options anyway. As a result, the `enableControlledPlacement` prop is no longer mandatory for the TooltipPopover component, as all diff --git a/docs/migrations/web/MIGRATION-v1.md b/docs/migrations/web/MIGRATION-v1.md index f9e48ca438..f702d97b0c 100644 --- a/docs/migrations/web/MIGRATION-v1.md +++ b/docs/migrations/web/MIGRATION-v1.md @@ -109,7 +109,7 @@ Use `data-spirit-fullwidthmode` instead of `Dropdown--fullWidth` and `data-break Remove the feature class which enabled this behavior. Remove feature class `.spirit-v1-links-underlined`, if used. -No other actions are required. However, if you didn't use the feature class, you might want to check if the links in your product design system components behave as expected in both hover and active states, because they are now underlined. +No other actions are required. However, if you didn’t use the feature class, you might want to check if the links in your product design system components behave as expected in both hover and active states, because they are now underlined. ## Update `TextField` and `TextArea` default disabled style [#DS-649](https://jira.lmc.cz/browse/DS-649) ([a7bb986](https://github.com/lmc-eu/spirit-design-system/commit/a7bb986)) @@ -131,7 +131,7 @@ The most notable change is that the mobile and desktop navigation are now separa - `HeaderDialog` Formerly, the desktop dialog (holding the site navigation) was a responsive CSS modification of a shared HTML code. -With the new `Header` and `HeaderDialog`, each component has its own instance of the navigation, i.e. the navigation code is duplicated. +With the new `Header` and `HeaderDialog`, each component has its own instance of the navigation, that is the navigation code is duplicated. This is because `HeaderDialog` will become an independent component in the future. You may need to take additional measures so your SEO is not affected by the duplicate HTML code of the navigation. @@ -188,7 +188,7 @@ If you need the `Stack` to have a spacing, add `hasSpacing` class. By default, ` - `
    ` → `
      ` -If you already used the feature class, you can remove it and don't need to do any other changes. +If you already used the feature class, you can remove it and don’t need to do any other changes. ## Remove `default` (now `neutral`) and `light` (`subtle`) `Tag` variants [#DS-648](https://jira.lmc.cz/browse/DS-648) ([f272c54](https://github.com/lmc-eu/spirit-design-system/commit/f272c54)) diff --git a/docs/migrations/web/MIGRATION-v2.md b/docs/migrations/web/MIGRATION-v2.md index 60c055fb84..430a0a120a 100644 --- a/docs/migrations/web/MIGRATION-v2.md +++ b/docs/migrations/web/MIGRATION-v2.md @@ -74,7 +74,7 @@ is now default. #### Migration Guide -You can now safely delete the CSS class `.spirit-feature-alert-enable-bordered` and/or the Sass variable +You can now safely delete the CSS class `.spirit-feature-alert-enable-bordered` and/or the SASS variable `$alert-enable-bordered` from your project as they have no effect. ### Dropdown: Shadow @@ -84,7 +84,7 @@ shadow is now default. #### Migration Guide -You can now safely delete the CSS class `.spirit-feature-dropdown-enable-enhanced-shadow` and/or the Sass variable +You can now safely delete the CSS class `.spirit-feature-dropdown-enable-enhanced-shadow` and/or the SASS variable `$dropdown-enable-enhanced-shadow` from your project as they have no effect. ### Modal: Uniform Variant @@ -94,7 +94,7 @@ uniform variant is now default. #### Migration Guide -You can now safely delete the CSS class `.spirit-feature-modal-enable-uniform-dialog` and/or the Sass variable +You can now safely delete the CSS class `.spirit-feature-modal-enable-uniform-dialog` and/or the SASS variable `$modal-enable-uniform-dialog` from your project as they have no effect. ### Tooltip: Controlled Placement @@ -104,7 +104,7 @@ was removed. The controlled placement is now default. #### Migration Guide -You can now safely delete the CSS class `.spirit-feature-tooltip-enable-data-placement` and/or the Sass variable +You can now safely delete the CSS class `.spirit-feature-tooltip-enable-data-placement` and/or the SASS variable `$tooltip-enable-data-placement` from your project as they have no effect. ## JavaScript Plugins @@ -114,7 +114,7 @@ You can now safely delete the CSS class `.spirit-feature-tooltip-enable-data-pla ### Tooltip: Floating UI only -Non-Floating-UI and CSS-only Tooltips are no longer supported. That's because we found out that most users want the +Non-Floating-UI and CSS-only Tooltips are no longer supported. That’s because we found out that most users want the advanced positioning options anyway. The Tooltip component is now dependent on the [Floating UI][floating-ui] library and has a new structure. See the updated [Tooltip documentation][readme-tooltip] for more details on how to use Tooltip now. @@ -286,7 +286,7 @@ wrapping component. Similarly, Tooltip (the tip itself) was renamed to TooltipPo 1. either add a new `.Tooltip` component wrapping the `.TooltipPopover`, or 2. rename your existing `.TooltipWrapper` to `.Tooltip`. -Also, Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That's because we found out that +Also, Tooltip now has a different API and uses the [Floating UI][floating-ui] library. That’s because we found out that most users want the advanced positioning options anyway. See [Tooltip documentation][readme-tooltip] for more details and examples. diff --git a/examples/next-with-app-router/README.md b/examples/next-with-app-router/README.md index e9039dd1e3..e14a0ef852 100644 --- a/examples/next-with-app-router/README.md +++ b/examples/next-with-app-router/README.md @@ -10,7 +10,7 @@ First, run the development server: yarn dev ``` -In case of error `npm error ERR! code ENOWORKSPACES`, please use `npx another telemetry disable`. For more information see [NPM error code ENOWORKSPACES with NextJS][npm-error-enoworkspaces]. +In case of error `npm error ERR! code ENOWORKSPACES`, please use `npx another telemetry disable`. For more information see [Npm error code ENOWORKSPACES with NextJS][npm-error-enoworkspaces]. Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. diff --git a/examples/next-with-pages-router/README.md b/examples/next-with-pages-router/README.md index 50111fda49..aee0b9fb05 100644 --- a/examples/next-with-pages-router/README.md +++ b/examples/next-with-pages-router/README.md @@ -10,7 +10,7 @@ First, run the development server: yarn dev ``` -In case of error `npm error ERR! code ENOWORKSPACES`, please use `npx another telemetry disable`. For more information see [NPM error code ENOWORKSPACES with NextJS][npm-error-enoworkspaces]. +In case of error `npm error ERR! code ENOWORKSPACES`, please use `npx another telemetry disable`. For more information see [Npm error code ENOWORKSPACES with NextJS][npm-error-enoworkspaces]. Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. diff --git a/exporters/svg/README.md b/exporters/svg/README.md index 5e11d1869c..04568f2404 100644 --- a/exporters/svg/README.md +++ b/exporters/svg/README.md @@ -18,7 +18,7 @@ This behavior can be fully customized by simply modifying the path generation te ## Installing -In order to make the Supernova SVG Asset exporter available for your organization so you can start generating code from your design system, please follow the installation guide in our [developer documentation](https://developers.supernova.io/using-exporters/installing-exporters). +To make the Supernova SVG Asset exporter available for your organization so you can start generating code from your design system, please follow the installation guide in our [developer documentation](https://developers.supernova.io/using-exporters/installing-exporters). ## Useful Links diff --git a/packages/analytics/README.md b/packages/analytics/README.md index 25390ade40..70156403e2 100644 --- a/packages/analytics/README.md +++ b/packages/analytics/README.md @@ -2,7 +2,7 @@ > Analytic tools for Spirit Design System. -Spirit-analytics is a simple CLI tool, which parses a repository with [react-scanner][react-scanner]. +Spirit-analytics is a simple command line tool, which parses a repository with [react-scanner][react-scanner]. The output is a JSON file or files with collected data. ## Install @@ -35,7 +35,7 @@ By default, the output will be saved into the `.scanner` directory, but you can spirit-analytics --output path/to/folder ``` -The [react-scanner] requires a [config file][react-scanner-config] to make it work, `spirit-analytics` has a default config inside, but if you need to, you can use your own config: +The [react-scanner] requires a [config file][react-scanner-config] to make it work, `spirit-analytics` has a default config inside, but to, you can use your own config: ```shell spirit-analytics --config path/to/config diff --git a/packages/codemods/README.md b/packages/codemods/README.md index a010d32efb..538c3702b9 100644 --- a/packages/codemods/README.md +++ b/packages/codemods/README.md @@ -4,7 +4,7 @@ `spirit-codemods` is a **CLI tool** designed to assist you in migrating to the latest version of our Spirit Design System library. This tool efficiently handles the removal of breaking changes and deprecations with simple commands. -For React transformations, it utilizes the [jscodeshift][jscodeshift] library. +For React transformations, it uses the [jscodeshift][jscodeshift] library. ## Install diff --git a/packages/design-tokens/README.md b/packages/design-tokens/README.md index bd2e454023..ba7778cce5 100644 --- a/packages/design-tokens/README.md +++ b/packages/design-tokens/README.md @@ -14,7 +14,7 @@ ## Available Design Tokens -| Category | Supernova | Figma | Sass | +| Category | Supernova | Figma | SASS | | ------------- | --------- | ----- | -------------------- | | 🖼 Borders | ✅ | ❌ | [`_borders.sass`] | | 🎨 Colors | ✅ | ✅ | [`_colors.sass`] | @@ -27,11 +27,11 @@ ## Install -🙋🏻‍♂️ **Hold on! Do you already use [`spirit-web`]?** Then you don't need to +🙋🏻‍♂️ **Hold on! Do you already use [`spirit-web`]?** Then you don’t need to install this package because `spirit-design-tokens` is installed automatically as a dependency of [`spirit-web`]. -If you want to use just `spirit-design-tokens` alone in your project, run: +To use just `spirit-design-tokens` alone in your project, run: ```shell yarn add @lmc-eu/spirit-design-tokens @@ -45,7 +45,7 @@ npm install --save @lmc-eu/spirit-design-tokens ## Basic Usage -The recommended approach in Sass is to import all Spirit design tokens at once +The recommended approach in SASS is to import all Spirit design tokens at once via the [`@tokens` API](#tokens-api): ```scss @@ -64,7 +64,7 @@ future.
      Optional: import by categories -You can also import individual design token files by categories, e.g.: +You can also import individual design token files by categories, for example: ```scss @use 'sass:map'; @@ -79,7 +79,7 @@ You can also import individual design token files by categories, e.g.: This approach is a bit more descriptive and thus provides slightly better developer experience. You may find it more convenient in situations you -**don't** suppose your code will make its way to Spirit as this approach is +**don’t** suppose your code will make its way to Spirit as this approach is incompatible with `@tokens` API that makes rebranding possible.
      @@ -98,7 +98,7 @@ The structure is the same as in the SASS. ## `@tokens` API -`@tokens` API enables quick and easy rebranding of Spirit Sass styles by +`@tokens` API enables quick and easy rebranding of Spirit SASS styles by [replacing the path](#b-via-load-path) to design tokens. You need to be familiar with it if you are building your custom design system based on Spirit or you are going to contribute to Spirit. @@ -109,7 +109,7 @@ going to contribute to Spirit. Access Spirit design tokens via the `@tokens` API without having to configure load path, just like shown in the [basic example](#basic-usage). This is a good -choice for starting off quickly. However, it **doesn't enable rebranding**. +choice for starting off quickly. However, it **doesn’t enable rebranding**. #### b) via load path @@ -128,9 +128,9 @@ while keeping them open to be replaced by another set of design tokens: ##### Configuring Load Path -Because the `@tokens` file doesn't exist locally, tell Sass where it should +Because the `@tokens` file doesn’t exist locally, tell SASS where it should look for unreachable files. This is also a required step if you are importing -Spirit components from their Sass source. +Spirit components from their SASS source. ```shell sass --load-path=node_modules/@lmc-eu/spirit-design-tokens/scss my-styles.scss @@ -174,7 +174,7 @@ module: { In Spirit, the [`@tokens.scss`] file simply @forwards all design tokens exposed by [`index.scss`] which in turn @forwards all design token categories. To make your design tokens compatible with Spirit, just create a `@tokens.scss` file and -@forward all your design tokens through it, e.g.: +@forward all your design tokens through it, for example: ```scss // @tokens.scss @@ -215,13 +215,13 @@ files in the directory. In order for developers to know the file behaves differently than usual Sass partials, a `@` prefix is added to mark this behavior both in filesystem and -inside Sass files. As a result, it's clear why e.g. `@use 'tools'` refers to -a local file and `@use '@tokens'` does not. However, **it's only a naming -convention,** there is no special tooling or configuration for Sass partials +inside SASS files. As a result, it’s clear why for example `@use 'tools'` refers to +a local file and `@use '@tokens'` does not. However, **it’s only a naming +convention,** there is no special tooling or configuration for SASS partials starting with `@`. Imported module **needs to be renamed to be compatible with SCSS** syntax -when it's used later on. That's why `@use '@tokens' as tokens`. +when it’s used later on. That’s why `@use '@tokens' as tokens`. Look at the following snippets and compare which one offers better comprehensibility. @@ -253,7 +253,7 @@ With `@` prefix: **Creating a custom design system derived from Spirit? Great to hear that! 🎉** -While it's perfectly OK to develop custom components that may not find their way +While it’s perfectly OK to develop custom components that may not find their way back to Spirit, your design tokens need to **include all Spirit design tokens** anyway, so all Spirit components you are going to reuse work correctly with your brand. @@ -265,7 +265,7 @@ Simply put, if you are going to build a design system based on Spirit: 3. feel free to add anything necessary on top of that, 4. use your design tokens in your code (and compile Spirit with them). -To make your Sass design tokens compatible with Spirit, don't forget to expose +To make your SASS design tokens compatible with Spirit, don’t forget to expose them via your custom [`@tokens` API](#tokens-api). diff --git a/packages/form-validations/README.md b/packages/form-validations/README.md index 71ead35dc7..feef82698a 100644 --- a/packages/form-validations/README.md +++ b/packages/form-validations/README.md @@ -69,7 +69,7 @@ FormValidations takes 3 parameters: - **form** - The form element -- **config** - An object containing the configuration. Default is Spirit's configuration which is +- **config** - An object containing the configuration. Default is Spirit’s configuration which is @@ -228,7 +228,7 @@ _Add a custom validator_ | ------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `element` | — | ✓ | The dom element where validator is applied to. | | `halt` | `false` | ✕ | Whether to stop validation of the field after this validator is applied on the field. When `true`, after this validator finishes validating, the rest of the validators are ignored on the current field. | -| `message` | — | ✓ | The message to show when the validation fails. It supports simple templating. `${0}` for the input's value, `${1}` and so on are for the attribute values. For the above example, `${0}` will get replaced by `myValue`, `${1}` by `10`, `${2}` by `20`, `${3}` by `dhaka`. It can also be a function which should return the error string. The values and inputs are available as function arguments | +| `message` | — | ✓ | The message to show when the validation fails. It supports simple templating. `${0}` for the input’s value, `${1}` and so on are for the attribute values. For the above example, `${0}` will get replaced by `myValue`, `${1}` by `10`, `${2}` by `20`, `${3}` by `dhaka`. It can also be a function which should return the error string. The values and inputs are available as function arguments | | `priority` | 1 | ✕ | Priority of the validator function. The higher the value, the earlier it gets called when there are multiple validators on one field. | | `validatorCallback` | — | ✓ | The function that validates the field. The value of the input field gets passed as the first parameter, and the attribute value (split using a comma) as the subsequent parameters. For example, for ``, the validator function gets called like `validatorCallback("myValue", 10, 20, "dhaka")`. Inside the function `this` refers to the input element | diff --git a/packages/icons/README.md b/packages/icons/README.md index 49d1a42082..365ba68ff1 100644 --- a/packages/icons/README.md +++ b/packages/icons/README.md @@ -4,11 +4,11 @@ ## Install -🙋🏻‍♂️ **Hold on! Do you already use [`spirit-web`]?** Then you don't need to +🙋🏻‍♂️ **Hold on! Do you already use [`spirit-web`]?** Then you don’t need to install this package because `spirit-icons` is installed automatically as a dependency of [`spirit-web`]. -If you want to use just `spirit-icons` alone in your project, run: +To use just `spirit-icons` alone in your project, run: ```shell yarn add @lmc-eu/spirit-icons