docs: add style checks for headings and content guidelines

.cspell.yaml

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

.github/workflows/main.yaml

@@ -55,3 +55,35 @@ 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
+
+      - name: ⚙️ Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24.14.0'
+
+      - name: ⬇️ Install Dependencies
+        # --legacy-peer-deps: starlight-llms-txt@0.10.0 requires astro@^6, but we're on astro@7.
+        # Remove once https://github.com/delucis/starlight-llms-txt/pull/127 is released.
+        run: npm ci --legacy-peer-deps
+
+      - name: 🏷️ Component Labels
+        run: node scripts/lint-component-labels.mjs

.vale.ini

@@ -0,0 +1,56 @@
+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
+# 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, both GitHub issue shorthand forms used in the docs
+#   (with and without the "shorebirdtech/" org prefix), 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.
+# - Shorebird.SecondPerson: same `existence` limitation as Exclamation
+#   above, now that it's error severity too (see SecondPerson.yml). Each
+#   entry masks a literal string that contains a first-person pronoun but
+#   isn't first-person prose:
+#   - "i.e." (without the trailing comma, which isn't part of the token
+#     match) - the abbreviation, not the pronoun "I"
+#   - the URL slug for the FAQ's "can I use Shorebird in my country?" anchor
+#   - "US" as in "United States", in the one place it's used that way
+#   - "My Organization", the literal default name Shorebird gives new orgs
+#   - "How We Bill", quoting the actual heading of the billing page section
+#   - the one deliberate first-person sentence in testing-patches.mdx: a
+#     direct privacy pledge reads better as "we never know" than as a
+#     passive "it never knows" (see PR #585 review discussion)
+TokenIgnores = (contact@shorebird\.dev), (console\.shorebird\.dev), \
+  (docs\.shorebird\.dev), (download\.flutter\.dev), (shorebird\.yaml), \
+  (shorebird yaml), (shorebirdtech/shorebird#\d+), (shorebird#\d+), \
+  (/path/to/flutter), \
+  (\[!\]), (Flutter Hot Reload), (i\.e\.), \
+  (#can-i-use-shorebird-in-my-country), (US regions), (My Organization), \
+  (How We Bill), (we _never_ know anything about your)

.vale/styles/Shorebird/Exclamation.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: 'Avoid exclamation points in documentation.'
+link: https://developers.google.com/style/exclamation-points
+level: error
+scope: text
+nonword: true
+# Allow [!] (literal flutter doctor output) but not bare exclamation points
+tokens:
+  - '!(?!\[)' # Negative lookahead: [!] is allowed

.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: error
+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)