diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c2fed5c55..e72cda3ffd 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! ❤️ +Thank you 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) @@ -74,7 +74,10 @@ 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 (e.g: CircleCI, Sauce Labs) or changes that affect the build system - **Deps**: Changes to dependencies - **Docs**: Documentation only changes - **Feat**: A new feature @@ -84,6 +87,7 @@ MUST be one of the following: - **Revert**: Reverting code changes - **Test**: Adding missing tests or correcting existing tests - **Style**: Changes to code style or styling of components and pages + ##### Scope @@ -110,7 +114,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 @@ -125,7 +129,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 @@ -150,7 +154,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 @@ -162,18 +166,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 @@ -183,9 +187,9 @@ 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 @@ -243,16 +247,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/apps/demo/config/vite/app.ts b/apps/demo/config/vite/app.ts index 944e3f4cea..0524134e28 100644 --- a/apps/demo/config/vite/app.ts +++ b/apps/demo/config/vite/app.ts @@ -77,7 +77,7 @@ export default defineConfig({ join(pathRelativeToRepositoryRoot, 'node_modules/@lmc-eu/spirit-design-tokens/src/scss'), ], // Silence deprecation warnings related to mixed declarations. - // We’ve disabled these warnings because they are evaluated as false positives in our context. + // We've disabled these warnings because they are evaluated as false positives in our context. // @see https://sass-lang.com/documentation/breaking-changes/mixed-decls/ for more details. silenceDeprecations: ['mixed-decls'], }, diff --git a/configs/typescript-config-spirit/README.md b/configs/typescript-config-spirit/README.md index 00cf9765d3..f850f380fe 100644 --- a/configs/typescript-config-spirit/README.md +++ b/configs/typescript-config-spirit/README.md @@ -27,7 +27,7 @@ It is worth noting that when you extend a `tsconfig.json` file, the properties i And **when both files define the same property, the child `tsconfig.json` wins**. However, this is not the case with `include` and `exclude`. -If you define them in the child `tsconfig.json` file, that **exact value will be used; it won’t be merged** with the value from the base `tsconfig.json` file. +If you define them in the child `tsconfig.json` file, that **exact value will be used; it won't be merged** with the value from the base `tsconfig.json` file. ### Base Configuration diff --git a/docs/DICTIONARIES.md b/docs/DICTIONARIES.md index 1ea1c22f8b..d578293075 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/contribution/experimental-code.md b/docs/contribution/experimental-code.md index a93653d949..6bef4c95c6 100644 --- a/docs/contribution/experimental-code.md +++ b/docs/contribution/experimental-code.md @@ -70,7 +70,7 @@ Some Spirit packages ship with available feature flags. These feature flags enable new behavior and styling, allowing you to opt-in to new breaking changes while remaining on the current major version. When a new feature flag is introduced it is marked `false` or "off" by default to ensure backward -compatibility. A feature flag may be configured in JavaScript, SASS, or both. +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`. @@ -98,7 +98,7 @@ As the usage of an existing flag increases or we determine a feature to be of hi 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` +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 @@ -171,7 +171,7 @@ be met to move a component from experimental to stable: - [ ] 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` diff --git a/docs/contribution/feature-flags.md b/docs/contribution/feature-flags.md index 6812888d9d..e8c2245ec3 100644 --- a/docs/contribution/feature-flags.md +++ b/docs/contribution/feature-flags.md @@ -3,12 +3,12 @@ ## Table of Contents - [Current feature flags](#current-feature-flags) -- [Turning on feature flags in SASS](#turning-on-feature-flags-in-sass) +- [Turning on feature flags in Sass](#turning-on-feature-flags-in-sass) The Spirit Design System codebase ships with a number of feature flags. These feature flags enable new behavior and styling, allowing you to opt-in to new (and sometimes breaking) changes while using the current version. A feature flag may -be configured in React, SASS, or both. +be configured in React, Sass, or both. This section documents each feature flag that is available and how to configure it. Folders and stories within this section in Storybook show components with all feature flags turned on. @@ -27,12 +27,12 @@ For more details on this approach, see the [feature flag documentation][feature-flag-documentation] in the Spirit Design System monorepo. -| Flag | Description | Default | SASS flag | +| Flag | Description | Default | Sass flag | | ---- | ----------- | ------- | --------- | -## Turning on Feature Flags in SASS +## Turning on Feature Flags in Sass -In SASS, you can enable feature flags in any of your stylesheets. Most often +In Sass, you can enable feature flags in any of your stylesheets. Most often this is done at the root/entrypoint stylesheet. You can enable or disable them by loading the `feature-flags` module with a configuration. @@ -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/003-typescript-only.md b/docs/decisions/003-typescript-only.md index 0e9fe2abbe..74e80984d8 100644 --- a/docs/decisions/003-typescript-only.md +++ b/docs/decisions/003-typescript-only.md @@ -20,7 +20,7 @@ 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 diff --git a/docs/migrations/web-react/migration-v1.md b/docs/migrations/web-react/migration-v1.md index 9330109859..a31006e384 100644 --- a/docs/migrations/web-react/migration-v1.md +++ b/docs/migrations/web-react/migration-v1.md @@ -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. diff --git a/docs/migrations/web-react/migration-v2.md b/docs/migrations/web-react/migration-v2.md index bf0969f86c..e121320c63 100644 --- a/docs/migrations/web-react/migration-v2.md +++ b/docs/migrations/web-react/migration-v2.md @@ -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 diff --git a/docs/migrations/web/migration-v1.md b/docs/migrations/web/migration-v1.md index f9e48ca438..81aa876e87 100644 --- a/docs/migrations/web/migration-v1.md +++ b/docs/migrations/web/migration-v1.md @@ -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. diff --git a/examples/next-with-app-router/README.md b/examples/next-with-app-router/README.md index 0069ade1f9..e7c7fb41dc 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 beddbd8427..7c127514ed 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/assets/README.md b/exporters/assets/README.md index 7a810e2ef7..36fea5199d 100644 --- a/exporters/assets/README.md +++ b/exporters/assets/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