docs: add style checks for headings and content guidelines

.cspell.yaml

@@ -90,6 +90,7 @@ words:
   - tabler
   - temurin
   - uiscene
+  - vvago
   - webkitallowfullscreen
   - widgetbook
   - xcarchive

.github/workflows/main.yaml

@@ -47,3 +47,22 @@ jobs:
     with:
       config: .cspell.yaml
       modified_files_only: false
+
+  style-check:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      checks: write
+      pull-requests: write
+
+    steps:
+      - name: 📚 Git Checkout
+        uses: actions/checkout@v7
+
+      - name: ✍️ Vale
+        uses: errata-ai/vale-action@v2
+        with:
+          reporter: github-pr-check
+          filter_mode: nofilter
+          fail_on_error: true

.vale.ini

@@ -0,0 +1,48 @@
+StylesPath = .vale/styles
+MinAlertLevel = warning
+Vocab = Shorebird
+
+[formats]
+mdx = md
+
+[*.{md,mdx}]
+BasedOnStyles = Shorebird, Vale
+# Only Vale.Terms (the Vocab-driven proper-noun check) is wanted from the
+# built-in Vale style; spell-checking is already handled by cspell.
+Vale.Spelling = NO
+Vale.Repetition = NO
+# Vale.Terms runs at error severity by default. Downgraded to warning
+# (non-blocking) because it doesn't respect code-fence exclusion the way
+# custom scope:text rules do: it flags literal shell commands inside
+# fenced code blocks (e.g. `shorebird release android`), and a TokenIgnores
+# pattern matching one occurrence intermittently fails to suppress a
+# *second* occurrence of the identical command elsewhere in the same file -
+# a genuine Vale bug (verified with minimal repros), not a config mistake.
+# Proper-noun capitalization is still reported, just doesn't block CI.
+Vale.Terms = warning
+# Global, rule-agnostic exceptions found while fixing every heading and
+# proper noun in the docs (see PRs #579 and #583). Headings-specific
+# exceptions (compound brand names, the numbered-list headings, "vs") live
+# in .vale/styles/Shorebird/Headings.yml's own exceptions list instead,
+# since that's scoped to just that rule. TokenIgnores is only needed here
+# for things with no rule-scoped alternative:
+# - Vale.Terms: a built-in, Vocab-driven check with no exceptions list of
+#   its own. Covers domains, an email address, a config filename mentioned
+#   two different ways, a GitHub issue shorthand, and a file path
+#   placeholder.
+# - Shorebird.Exclamation: the `existence` extension type doesn't support
+#   an exceptions list the way `capitalization` does (verified). Covers a
+#   table row documenting the literal "[!]" symbol from real `flutter
+#   doctor` output.
+# - Shorebird.Headings: "Flutter Hot Reload" can't be a Headings.yml
+#   exceptions entry (bare "Reload" or the phrase "Hot Reload" both
+#   collide with ordinary lowercase "hot reload" prose used as headings
+#   elsewhere - capitalization exceptions match case-insensitively and
+#   then want the exception's exact case, which misfires there).
+#   TokenIgnores does plain literal-text redaction with no such
+#   case-insensitive side effect, so it's the only safe option for this
+#   one heading.
+TokenIgnores = (contact@shorebird\.dev), (console\.shorebird\.dev), \
+  (docs\.shorebird\.dev), (download\.flutter\.dev), (shorebird\.yaml), \
+  (shorebird yaml), (shorebirdtech/shorebird#\d+), (/path/to/flutter), \
+  (\[!\]), (Flutter Hot Reload)

.vale/styles/Shorebird/Exclamation.yml

@@ -0,0 +1,8 @@
+extends: existence
+message: 'Avoid exclamation points in documentation.'
+link: https://developers.google.com/style/exclamation-points
+level: error
+scope: text
+nonword: true
+tokens:
+  - '!(?!\[)'

.vale/styles/Shorebird/Headings.yml

@@ -0,0 +1,93 @@
+extends: capitalization
+message:
+  "'%s' should use sentence case (capitalize only the first word and proper
+  nouns)"
+link: https://developers.google.com/style/capitalization
+level: error
+scope: heading
+match: $sentence
+exceptions:
+  - Shorebird
+  - Shorebird's
+  - Flutter
+  - Flutter's
+  - Dart
+  - Android
+  - iOS
+  - macOS
+  - Windows
+  - Linux
+  - Ubuntu
+  - Xcode
+  - GitHub
+  - CocoaPods
+  - Codemagic
+  - Fastlane
+  - Sentry
+  - Crashlytics
+  - Firebase
+  - Firestore
+  - TestFlight
+  - Darkly
+  - Google
+  - Play
+  - Store
+  - HashiCorp
+  - Vault
+  - Azure
+  - AWS
+  - GCP
+  - KMS
+  - CLI
+  - CI
+  - SDK
+  - API
+  - UI
+  - URL
+  - JSON
+  - YAML
+  - TLS
+  - PEM
+  - DER
+  - RSA
+  - OTA
+  - MDM
+  - PR
+  - OS
+  - APKs
+  - VS
+  - Podfile
+  - Swift
+  - Kotlin
+  - Java
+  - Objective-C
+  - BLoC
+  - npm
+  - I
+  - I'm
+  - I've
+  - I'll
+  - Stripe
+  - Fastfile
+  - BuildContext
+  - RenderObject
+  - Apple
+  - 1Password
+  - AOT
+  - GuardSquare
+  - LTS
+  - ExportOptions.plist
+  - Skia
+  - Impeller
+  - vs
+  - Remote
+  - Config
+  - Launch
+  - Azure Key Vault
+  - App Store Connect
+  - The Status Enum
+  - The Single State Class
+  - The Events
+  - Framework Search Paths
+  - GCP Cloud KMS
+  - React Native

.vale/styles/Shorebird/SecondPerson.yml

@@ -0,0 +1,21 @@
+extends: existence
+message:
+  '''%s'' is first person; docs should be written in second person ("you")'
+level: warning
+scope: paragraph
+ignorecase: true
+tokens:
+  - "\\bI\\b"
+  - "\\bI'm\\b"
+  - "\\bI've\\b"
+  - "\\bI'll\\b"
+  - "\\bwe\\b"
+  - "\\bwe're\\b"
+  - "\\bwe've\\b"
+  - "\\bwe'll\\b"
+  - "\\bour\\b"
+  - "\\bours\\b"
+  - "\\bus\\b"
+  - "\\blet's\\b"
+  - "\\bmy\\b"
+  - "\\bmine\\b"

.vale/styles/config/vocabularies/Shorebird/accept.txt

@@ -0,0 +1,3 @@
+Shorebird
+Flutter
+Code Push

README.md

@@ -1,4 +1,4 @@
-# Shorebird Docs 🐦📚
+# Shorebird docs 🐦📚
 
 [![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)