Add Vale prose linting to feature descriptions

ddbeck · ddbeck · commit 63796702a5ad · 2025-06-11T15:53:03.000+02:00
diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
@@ -29,6 +29,14 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm test
+  vale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1
+        with:
+          fail_on_error: true
+          version: 3.12.0
 
 env:
   FORCE_COLOR: 3
diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,6 @@
+StylesPath = .vale
+
+[features/*.yml]
+View = features
+BasedOnStyles = Vale, web-features-styles
+Vale.Spelling = NO
diff --git a/.vale/config/views/features.yml b/.vale/config/views/features.yml
@@ -0,0 +1,5 @@
+engine: dasel
+scopes:
+  - name: description
+    expr: description
+    type: md
diff --git a/.vale/web-features-styles/Avoid.yml b/.vale/web-features-styles/Avoid.yml
@@ -0,0 +1,6 @@
+extends: existence
+message: Consider removing '%s'
+level: warning
+ignorecase: true
+tokens:
+  - is used to
diff --git a/.vale/web-features-styles/Substitute.yml b/.vale/web-features-styles/Substitute.yml
@@ -0,0 +1,9 @@
+extends: substitution
+message: Consider using '%s' instead of '%s'
+level: warning
+ignorecase: false
+# swap maps tokens in form of bad: good
+swap:
+  defines: sets
+  specifies: sets
+  determines: sets
diff --git a/docs/guidelines.md b/docs/guidelines.md
@@ -79,6 +79,11 @@ The identifier should match the name, with these additional guidelines:
 
 ## Descriptions
 
+> [!TIP]
+> Some description rules are enforced by linting with Vale.
+> A workflow reviews files that you change in your pull request and suggest changes.
+> To run the Vale linter locally, [install Vale](https://vale.sh/docs/install) and run `vale .` from the root of the repository.
+
 The `description` field contains a short description of the feature in Markdown-formatted text, which is converted to HTML in the published package.
 Follow the general writing guidelines in this section, but see the [word and phrase list](#word-and-phrase-list) for specific usage instructions.
 
@@ -158,12 +163,16 @@ Avoid.
 See [sets](#sets).
 ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
 
+⚠️ Warned by vale: [`Substitute.yml`](/.vale/web-features-styles/Substitute.yml)
+
 #### determines
 
 Avoid.
 See [sets](#sets).
 ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
 
+⚠️ Warned by vale: [`Substitute.yml`](/.vale/web-features-styles/Substitute.yml)
+
 #### device
 
 Use "device" to refer to the underlying operating system or hardware environment, or combination thereof.
@@ -195,6 +204,8 @@ Omit "is used" where there's no loss in meaning.
 For example, prefer "The feature reads…" over "The feature is used to read…"
 ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635981))
 
+✅ Required by vale: [`Avoid.yml`](/.vale/web-features-styles/Avoid.yml)
+
 #### longhands and shorthands
 
 Use the terms "shorthand" and "longhand" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties. 
@@ -231,6 +242,8 @@ Avoid.
 See [sets](#sets).
 ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491))
 
+⚠️ Warned by vale: [`Substitute.yml`](/.vale/web-features-styles/Substitute.yml)
+
 #### styling … as … by default
 
 Use this phrase (or using another appropriate preposition, such as "styling in") to note conventional or standardized default styling.
diff --git a/features/beforeunload.yml b/features/beforeunload.yml
@@ -1,5 +1,5 @@
 name: beforeunload
-description: "The `beforeunload` event is fired when the current window is about to be unloaded. Typically this is used to display a dialog to confirm if users really want to leave the page when there is unsaved data that would be lost."
+description: "The `beforeunload` event is fired when the current window is about to be unloaded. Typically you use this to display a dialog to confirm if users really want to leave the page when there is unsaved data that would be lost."
 spec: https://html.spec.whatwg.org/multipage/nav-history-apis.html#the-beforeunloadevent-interface
 status:
   compute_from: api.Window.beforeunload_event
diff --git a/features/charset.yml b/features/charset.yml
@@ -1,5 +1,5 @@
 name: "@charset"
-description: The `@charset` CSS at-rule specifies the character encoding of an external style sheet.
+description: The `@charset` CSS at-rule specifies  the character encoding of an external style sheet.
 spec: https://drafts.csswg.org/css2/#charset
 group: css
 compat_features:
diff --git a/features/del.yml b/features/del.yml
@@ -1,5 +1,5 @@
 name: <del>
-description: The `<del>` element element represents a range of text that has been deleted from a document, styling text as strikethrough by default.
+description: The `<del>` element  element represents a range of text that has been deleted from a document, styling text as strikethrough by default.
 spec: https://html.spec.whatwg.org/multipage/edits.html#the-del-element
 group: html-elements
 compat_features:
diff --git a/features/font-kerning.yml b/features/font-kerning.yml
@@ -1,5 +1,5 @@
 name: font-kerning
-description: The `font-kerning` CSS property sets whether kerning data from a font is used to adjust the space between letters.
+description: The `font-kerning` CSS property sets whether to use kerning data from a font to adjust the space between letters.
 spec: https://drafts.csswg.org/css-fonts-4/#font-kerning-prop
 group: font-features
 caniuse: font-kerning
diff --git a/features/form-associated-custom-elements.yml b/features/form-associated-custom-elements.yml
@@ -1,5 +1,5 @@
 name: Form-associated custom elements
-description: Custom elements may act like built-in form elements, via the the `attachInternals()` method of `HTMLElement` and the `ElementInternals` API.
+description: Custom elements may act like built-in form elements, via the `attachInternals()` method of `HTMLElement` and the `ElementInternals` API.
 spec: https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements
 group:
   - custom-elements
diff --git a/features/hidden-until-found.yml b/features/hidden-until-found.yml
@@ -1,5 +1,5 @@
 name: hidden="until-found"
-description: 'The `hidden="until-found"` attribute hides an element until it is found using the browser''s find-in-page search or it is directly navigated to by following a URL fragment.'
+description: The `hidden="until-found"` attribute hides an element until it is found using the browser's find-in-page search or it is directly navigated to by following a URL fragment.
 spec: https://html.spec.whatwg.org/multipage/interaction.html#attr-hidden-until-found
 group: html
 compat_features:
diff --git a/features/idle-detection.yml b/features/idle-detection.yml
@@ -1,3 +1,3 @@
 name: Idle detection
-description: The `IdleDetector` API is used to notify a webpage of the user's idle, active, and locked state.
+description: The `IdleDetector` API notifies a webpage of the user's idle, active, and locked state.
 spec: https://wicg.github.io/idle-detection/
diff --git a/features/ins.yml b/features/ins.yml
@@ -1,5 +1,5 @@
 name: <ins>
-description: The `<ins>` element element represents a range of text that has been inserted into a document, styling text as underlined by default.
+description: The `<ins>` element represents a range of text that has been inserted into a document, styling text as underlined by default.
 spec: https://html.spec.whatwg.org/multipage/edits.html#the-ins-element
 group: html-elements
 # TODO - Removed until #1173 is resolved, these APIs are currently listed
diff --git a/features/optional-catch-binding.yml b/features/optional-catch-binding.yml
@@ -1,5 +1,5 @@
 name: Optional catch binding
-description: Omit the the binding parameter of a `catch` clause when you don't need information about the exception in a `try ... catch` statement.
+description: Omit the binding parameter of a `catch` clause when you don't need information about the exception in a `try ... catch` statement.
 spec: https://tc39.es/ecma262/multipage/ecmascript-language-statements-and-declarations.html#sec-try-statement
 group: javascript
 snapshot: ecmascript-2019
diff --git a/features/print-events.yml b/features/print-events.yml
@@ -1,5 +1,5 @@
 name: Print events
-description: An alternative to `@media print` queries, the `beforeprint` and `afterprint` events allow you to change the page for printing and and restore the page after printing.
+description: An alternative to `@media print` queries, the `beforeprint` and `afterprint` events allow you to change the page for printing and restore the page after printing.
 group: print
 spec:
   - https://html.spec.whatwg.org/multipage/indices.html#event-afterprint
