[core] Setup vale for enforcing style guides (mui#39633)

.github/styles/Blog/ComposedWords.yml

@@ -0,0 +1,13 @@
+extends: substitution
+message: To be consistent with the rest of the documentation, consider using '%s' instead of '%s'.
+level: warning
+ignorecase: true
+# swap maps tokens in form of bad: good
+# for more information: https://vale.sh/docs/topics/styles/#substitution
+swap:
+  sub-component: subcomponent
+  sub-components: subcomponents
+  'sub component': subcomponent
+  'sub components': subcomponents
+  'use-case': 'use case'
+  'usecase': 'use case'

.github/styles/Blog/NamingConventions.yml

@@ -0,0 +1,17 @@
+extends: substitution
+message: To be consistent with capitalization, consider using '%s' instead of '%s'.
+level: warning
+ignorecase: false
+# swap maps tokens in form of bad: good
+# for more information: https://vale.sh/docs/topics/styles/#substitution
+swap:
+  api: API
+  Api: API
+  typescript: TypeScript
+  Typescript: TypeScript
+  ts: TypeScript
+  TS: TypeScript
+  javascript: JavaScript
+  Javascript: JavaScript
+  css: CSS
+  Css: CSS

.github/styles/Blog/Typos.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: Do you mean '%s' instead of '%s'?
+level: warning
+ignorecase: true
+# swap maps tokens in form of bad: good
+# for more information: https://vale.sh/docs/topics/styles/#substitution
+swap:
+  bellow: below

.github/workflows/vale-action.yml

@@ -0,0 +1,23 @@
+name: Vale action
+
+on: [pull_request]
+
+permissions: {}
+
+jobs:
+  vale:
+    name: runner / vale
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - uses: errata-ai/vale-action@c4213d4de3d5f718b8497bd86161531c78992084 # v2.0.1
+        with:
+          reporter: github-pr-review
+          files: docs/data
+        env:
+          # Required, set by GitHub actions automatically:
+          # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -37,3 +37,6 @@ node_modules
 package-lock.json
 size-snapshot.json
 docs/public/static/blog/feed/*
+# vale downloaded config
+.github/styles/Google
+.github/styles/write-good

.vale.ini

@@ -0,0 +1,32 @@
+# Config vale. More information at https://docs.errata.ai/vale/config
+StylesPath = .github/styles
+MinAlertLevel = suggestion
+
+Packages = Google
+
+[*.md]
+# Ignore code injection which start with {{...
+BlockIgnores = {{.*
+
+# Custom syle
+# BasedOnStyles = Blog
+
+Blog.ComposedWords = YES
+Blog.NamingConventions = YES
+Blog.Typos = YES
+
+# 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.
+
+# 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

docs/data/base/components/focus-trap/focus-trap.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"}}

docs/data/base/guides/working-with-tailwind-css/working-with-tailwind-css.md

@@ -27,7 +27,7 @@ All credits go to the Tailwind Labs team for designing this component, found on
 
 ## Setting up the project
 
-We'll use [`create-react-app` with typescript](https://create-react-app.dev/docs/adding-typescript/#installation) for this guide.
+We'll use [`create-react-app` with TypeScript](https://create-react-app.dev/docs/adding-typescript/#installation) for this guide.
 After you have created the project, follow the instructions given on the [Tailwind CSS installation page](https://tailwindcss.com/docs/guides/create-react-app) in order to configure `tailwind`.
 Next, install `@mui/base` in the project:
 

docs/data/material/components/selects/selects.md

@@ -30,7 +30,7 @@ It's meant to be an improved version of the "react-select" and "downshift" packa
 ## Props
 
 The Select component is implemented as a custom `<input>` element of the [InputBase](/material-ui/api/input-base/).
-It extends the [text field components](/material-ui/react-text-field/) sub-components, either the [OutlinedInput](/material-ui/api/outlined-input/), [Input](/material-ui/api/input/), or [FilledInput](/material-ui/api/filled-input/), depending on the variant selected.
+It extends the [text field components](/material-ui/react-text-field/) subcomponents, either the [OutlinedInput](/material-ui/api/outlined-input/), [Input](/material-ui/api/input/), or [FilledInput](/material-ui/api/filled-input/), depending on the variant selected.
 It shares the same styles and many of the same props. Refer to the respective component's API page for details.
 
 ### Filled and standard variants

docs/data/material/guides/api/api.md

@@ -79,7 +79,7 @@ Nested components inside a component have:
 
 - their own flattened props when these are key to the top level component abstraction,
   for instance an `id` prop for the `Input` component.
-- their own `xxxProps` prop when users might need to tweak the internal render method's sub-components,
+- their own `xxxProps` prop when users might need to tweak the internal render method's subcomponents,
   for instance, exposing the `inputProps` and `InputProps` props on components that use `Input` internally.
 - their own `xxxComponent` prop for performing component injection.
 - their own `xxxRef` prop when you might need to perform imperative actions,

docs/data/material/guides/interoperability/interoperability.md

@@ -295,7 +295,7 @@ If, however, you would like to use styled-components, you can configure your app
 <!-- #default-branch-switch -->
 
 - [Create React App with styled-components](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components)
-- [Create React App with styled-components and typescript](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts)
+- [Create React App with styled-components and TypeScript](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts)
 
 Following this approach reduces the bundle size, and removes the need to configure the CSS injection order.
 

docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md

@@ -114,7 +114,7 @@ const myCustomDefaultTheme = extendTheme();
 export default myCustomDefaultTheme;
 ```
 
-Here, the returned `theme` object needs to follow a certain structure to be used correctly by the final `CssVarsProvider`. It should have a `colorSchemes` key with the light and dark (and any other) palette. `prepareCssVars` import from `@mui/system` is used to create css variable names which can then be easily accessed using the returned `vars`. This is also added to the `theme` object. Finally, `myCustomDefaultTheme` theme object is created that can now be passed to the `createCssVarsProvider` to get a `CssVarsProvider`.
+Here, the returned `theme` object needs to follow a certain structure to be used correctly by the final `CssVarsProvider`. It should have a `colorSchemes` key with the light and dark (and any other) palette. `prepareCssVars` import from `@mui/system` is used to create CSS variable names which can then be easily accessed using the returned `vars`. This is also added to the `theme` object. Finally, `myCustomDefaultTheme` theme object is created that can now be passed to the `createCssVarsProvider` to get a `CssVarsProvider`.
 
 ```js
 // CssVarsProvider.js
@@ -133,7 +133,7 @@ export { CssVarsProvider, useColorScheme };
 
 Now wrap your top level app component with this `CssVarsProvider` component and then you can access the passed theme value to any of the components rendered inside the provider.
 
-Example of a component using the css variable -
+Example of a component using the CSS variable -
 
 ```js
 // Button.js