[docs] Fix some Vale errors (#41516)

Author: oliviertassinari

.circleci/config.yml

@@ -62,7 +62,7 @@ commands:
       browsers:
         type: boolean
         default: false
-        description: 'Set to true if you intend to any browser (e.g. with playwright).'
+        description: 'Set to true if you intend to any browser (for example with playwright).'
 
     steps:
       - run:

.vale.ini

@@ -1,28 +1,23 @@
-# Config vale. More information at https://docs.errata.ai/vale/config
+# Vale config. More information at https://vale.sh/docs/topics/config/
 StylesPath = .github/styles
-MinAlertLevel = suggestion
+MinAlertLevel = warning
 
-# The docs/writing-rules.zip is generated by `pnpm docs:zipRules`
-Packages = Google, docs/writing-rules.zip
+# The docs/mui-vale.zip is generated by `pnpm docs:zipRules`
+Packages = Google,docs/mui-vale.zip
 
 [*.md]
-# Ignore code injection which start with {{...
+# Ignore code injections that start with {{...
 BlockIgnores = {{.*
 
-BasedOnStyles = writing-rules
+BasedOnStyles = MUI
 
-# Google:
-Google.FirstPerson = YES # Avoid first-person pronouns such as I, me, ...'.
-Google.GenderBias = YES # Avoid gendered profession
-Google.OxfordComma = YES
-Google.Quotes = YES # Commas and periods go inside quotation marks.
-Google.Spelling = YES # In general, use American spelling (word ending with 'nised' or 'logue')
-Google.We = YES # Try to avoid using first-person plural
-Google.Latin = YES # Try to avoid latin expressions e.g. and i.e.
+# Google errors:
+Google.GenderBias = YES # No Gender bias
+# Google warings:
+Google.FirstPerson = YES # Avoid first-person
+Google.We = YES # Avoid first-person plural
+Google.Will = YES # Avoid future tense
+Google.OxfordComma = YES # Prefer Oxford comma
 
-# Those rules are not repected a lot
-# Google.Passive = YES # In general, use active voice instead of passive voice.
-Google.Will = YES # Avoid using will
-
-# False positives with "1st" nearly no use in our doc
-# Google.Units = YES # Put a nonbreaking space between the number and the unit
+[CHANGELOG*.md]
+MUI.CorrectReferenceAllCases = NO

CHANGELOG.md

@@ -253,7 +253,7 @@ Click on **Details** to find out more about them.
 ### Updating the component API documentation
 
 The component API in the component `propTypes` and under `docs/pages/api-docs` is auto-generated from the [JSDoc](https://jsdoc.app/about-getting-started.html) in the TypeScript declarations.
-Be sure to update the documentation in the corresponding `.d.ts` files (e.g. `packages/mui-material/src/Button/Button.d.ts` for `<Button>`) and then run:
+Be sure to update the documentation in the corresponding `.d.ts` files (for example `packages/mui-material/src/Button/Button.d.ts` for `<Button>`) and then run:
 
 ```bash
 $ pnpm proptypes
@@ -300,11 +300,11 @@ docs/src/pages/components/buttons/
 #### 2. Write the demo code
 
 We uses TypeScript to document our components.
-We prefer demos written in TS (using the `.tsx` file format).
+We prefer demos written in TypeScript (using the `.tsx` file format).
 
 After creating a TypeScript demo, run `pnpm docs:typescript:formatted` to automatically create the JavaScript version, which is also required.
 
-If you're not familiar with TypeScript, you can write the demo in JavaScript, and a core contributor may help you migrate it to TS.
+If you're not familiar with TypeScript, you can write the demo in JavaScript, and a core contributor may help you migrate it to TypeScript.
 
 #### 3. Edit the page's Markdown file
 

CHANGELOG.old.md

@@ -117,15 +117,15 @@ You can find complete templates and themes in the [MUI Store](https://mui.com/s
 Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
 
 Contributing is about more than just issues and pull requests!
-There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
+There are many other ways to [support Material UI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
 
 ## Changelog
 
 The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release.
 
 ## Roadmap
 
-Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
+Future plans and high-priority features and enhancements can be found in the [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
 
 ## License
 

CONTRIBUTING.md

@@ -8,7 +8,7 @@
 
 ### `Props Interface`
 
-- export interface `{ComponentName}classes` from `{component}Classes.ts` and add comment for generating api docs (for internal components, may or may not expose classes but don't need comment)
+- export interface `{ComponentName}classes` from `{component}Classes.ts` and add comment for generating API docs (for internal components, may or may not expose classes but don't need comment)
 - export interface `{ComponentName}Props`
 - always export props interface (use `interface` over `type`) from the component file
 

README.md

@@ -194,7 +194,7 @@ function addDeployPreviewUrls() {
     const fragments = url.split('/').reverse();
     if (fragments[0] === fragments[1]) {
       // check if the end of pathname is the same as the one before
-      // e.g. `/data/material/getting-started/overview/overview.md
+      // for example `/data/material/getting-started/overview/overview.md
       url = fragments.slice(1).reverse().join('/');
     }
 

TYPESCRIPT_CONVENTION.md

@@ -78,7 +78,7 @@ The following demo uses the [Portal](/base-ui/react-portal/) component to render
 
 ### Using a toggle inside the trap
 
-The most common use-case for the Focus Trap component is to maintain focus within a [Modal](/base-ui/react-modal/) component that is entirely separate from the element that opens the modal.
+The most common use case for the Focus Trap component is to maintain focus within a [Modal](/base-ui/react-modal/) component that is entirely separate from the element that opens the modal.
 But you can also create a toggle button for the `open` prop of the Focus Trap component that is stored inside of the component itself, as shown in the following demo:
 
 {{"demo": "ContainedToggleTrappedFocus.js"}}

dangerfile.ts

@@ -82,7 +82,7 @@ The demo below shows how to integrate this hook with its component counterpart:
 
 {{"demo": "UseFormControl.js", "defaultCodeOpen": false}}
 
-Note that even though Form Control supports both controlled and uncontrolled-style APIs (i.e. it accepts `value` and `defaultValue` props), `useFormControlContext` returns only the controlled `value`.
+Note that even though Form Control supports both controlled and uncontrolled-style APIs (that is it accepts `value` and `defaultValue` props), `useFormControlContext` returns only the controlled `value`.
 This way, you don't have to implement both in your custom input—Form Control does this for you.
 
 :::info