Updated Vale. Tested pages

Author: Tony Sansone

.vale.ini

@@ -1,9 +1,12 @@
 StylesPath = styles
 
 MinAlertLevel = suggestion
+
+IgnoredScopes = code, tt
+
 Vocab = Base, Google
 
-Packages = Google, proselint, write-good, Readability
+Packages = Google, proselint, Readability
 
 [*]
-BasedOnStyles = Vale, Google, proselint, write-good, Readability
+BasedOnStyles = Vale, Google, proselint, Readability

README.md

@@ -4,19 +4,19 @@
 [![OpenSSF Scorecard SVG][]][Scorecard Results]
 [![first-timers SVG][]][first-timers]
 
-The https://dart.dev site, built with [Jekyll][] and hosted on [Firebase][].
+The [Dart](https://dart.dev) site, built with [Jekyll][] and hosted on [Firebase][].
 
-[We welcome contributions](CONTRIBUTING.md),
-and we're [first-timer friendly][first-timers]!
+[The Flutter team welcomes contributions](CONTRIBUTING.md),
+and [first-time contributors][first-timers]!
 
 ## Getting started
 
-Start by looking for an [issue](https://github.com/dart-lang/site-www/issues)
+To start, look for an [issue](https://github.com/dart-lang/site-www/issues)
 that catches your interest, or create an issue with your proposed change.
-Ask for the issue to be assigned to you.
+Ask someone to assign the issue to you.
 
 To update this site, fork the repo, make your changes, and generate a pull
-request. For simple changes (such as to CSS and text), you probably don't need
+request. For simple changes like CSS and text, you shouldn't need
 to build this site. Often you can make changes using the GitHub UI.
 
 > **NOTE:** If you clone this repo locally,
@@ -49,17 +49,17 @@ Install the following tools, if you don't have them already:
 
 - **GNU Make**.
   On Windows the easiest way to install Make is `choco install make`
-  using command prompt or powershell as an admin.
+  using command prompt or PowerShell as an admin.
   Other options include using a [subsystem][wsl].
 
 - **Docker**.
-  We use Docker for local dev, tests, and building the site.
+  To develop, test, and build the site, use Docker.
   Install it from https://docs.docker.com/get-docker/.
 
 - **Firebase CLI**, for hosting the site locally.
-  One way to get this is to run `npm install -g firebase-tools`.
+  Run `npm install -g firebase-tools`.
   For full setup details,
-  read the [Firebase CLI documentation](https://firebase.google.com/docs/cli).
+  check out the [Firebase CLI documentation](https://firebase.google.com/docs/cli).
 
 ### 2. Clone this repo _and_ its submodules
 
@@ -105,7 +105,7 @@ _choose one_ of the following submodule-cloning techniques:
    $ git checkout -b <BRANCH_NAME>
    ```
 
-2. If the Docker Desktop application isn't already running on your machine,
+2. If the Docker Desktop app isn't already running on your machine,
    start it. Look for the Docker status icon: if it has an exclamation
    point (`!`), then update Docker Desktop before proceeding.
 
@@ -127,12 +127,12 @@ _choose one_ of the following submodule-cloning techniques:
 
 5. View your changes in the browser by navigating to `http://localhost:4000`.
    > **Note:** Unless you're editing files under `site-shared`,
-   > you can safely ignore `ERROR: directory is already being watched` messages.
+   > you can ignore `ERROR: directory is already being watched` messages.
    > For details, see [#1363](https://github.com/flutter/website/issues/1363).
 
 6. Make your changes to the local repo.
 
-   The site will rebuild and the browser will autoreload to reflect the changes.
+   The site rebuilds and the browser reloads to reflect the changes.
 
    > **Tip:** If you aren't seeing the changes you expect (e.g. src/_data),
    > <kbd>Ctrl</kbd> + <kbd>C</kbd> out of your running dev server and rebuild the site from scratch
@@ -151,7 +151,7 @@ _choose one_ of the following submodule-cloning techniques:
    $ make down
    ```
 
-> **Tip:** To find additional commands, read the [Makefile][].
+> **Tip:** To find more commands, read the [Makefile][].
 > For example, if you need to debug the Docker setup,
 > you can run:
 >
@@ -207,17 +207,17 @@ personal Firebase hosting staging site as follows:
    $ make build
    ```
 
-   This will build the site and copy it to your local `_site` directory.
-   If that directory previously existed, it will be replaced.
+   This command builds the site and copy it to your local `_site` directory.
+   If that directory existed, the command replaces it.
 
 1. Deploy to your activated Firebase project's default hosting site:
 
    ```terminal
    $ FIREBASE_PROJECT=<your-project> make deploy
    ```
 
-   > **TIP:** Add your `FIREBASE_PROJECT` env var to your `.env` file
-   > and it will overwrite the default every time you deploy without specifying.
+   > **Tip:** Add your `FIREBASE_PROJECT` env var to your `.env` file
+   > and it overwrites the default every time you deploy without specifying.
 
 1. Navigate to your PR on GitHub and update it with the location of
   the staged version, the names of your reviewers, and so on.

src/null-safety/index.md

@@ -10,11 +10,11 @@ of variables set to `null`.
 
 For example, if a method expects an integer but receives `null`,
 your app causes a runtime error.
-This type of error, a null dereference error, can be difficult to debug.
+This error type, a null dereference error, can be difficult to debug.
 
 With sound null safety, all variables require a value.
 This means Dart considers all variables _non-nullable_.
-You can assign values of the declared type only, like `int i=42`.
+You can assign values of the declared type, like `int i=42`.
 You can never assign a value of `null` to default variable types.
 To specify that a variable type can have a `null` value, add a `?` after
 the type annotation: `int? i`.
@@ -42,7 +42,7 @@ final b = Foo();
 ```
 
 <a id="creating-variables"></a>
-To indicate that a variable might have the value `null`,
+To show that a variable might have the value `null`,
 just add `?` to its type declaration:
 
 ```dart
@@ -54,43 +54,42 @@ int? aNullableInt = null;
 - To learn more about this topic, see
   [Understanding null safety](/null-safety/understanding-null-safety).
 
-
 ## Null safety principles
 
 Dart supports null safety using the following two core design principles:
 
-* **Non-nullable by default**. Unless you explicitly tell Dart that a variable
-   can be null, it's considered non-nullable. This default was chosen
-   after research found that non-null was by far the most common choice in APIs.
-
-* **Fully sound**. Dart's null safety is sound, which enables compiler optimizations.
-  If the type system determines that something isn't null, then that thing can _never_ be
-  null. Once you migrate your whole project
-  and its dependencies to null safety, 
-  you reap the full benefits of soundness—not only 
-  fewer bugs, but smaller binaries and faster execution.
+* **Non-nullable by default**. Unless you set a variable to allow null,
+  it's considered non-nullable.
+  The Dart team chose this default after research found that APIs
+  chose non-null more often.
 
+* **Fully sound**. Dart's null safety is sound,
+  which enables compiler optimizations.
+  If the type system determines that something isn't null,
+  then that thing can _never_ be null.
+  Once you migrate your whole project and its dependencies to null safety,
+  you reap the full benefits of soundness—not only fewer bugs,
+  but smaller binaries and faster execution.
 
 ## Dart 3 and null safety
 
 Dart 3 has built-in sound null safety.
 Dart 3 prevents code without it from running.
 
-To learn how to migrate to Dart 3, 
-check out the [Dart 3 migration guide](/resources/dart-3-migration).
+To learn how to migrate to Dart 3,
+review the [Dart 3 migration guide](/resources/dart-3-migration).
 Packages developed without null safety support cause issues
 when resolving dependencies:
 
 ```terminal
 $ dart pub get
 
-Because pkg1 doesn't support null safety, version solving failed.
+Because `pkg1` doesn't support null safety, version solving failed.
 The lower bound of "sdk: '>=2.9.0 <3.0.0'" must be 2.12.0 or higher to enable null safety.
 ```
 
 Libraries incompatible with Dart 3 cause analysis or compilation errors.
 
-
 ```terminal
 $ dart analyze .
 Analyzing ....                         0.6s
@@ -111,10 +110,10 @@ To resolve these issues:
 
 1. Check for [null safe versions](/null-safety/migration-guide#check-dependency-status)
    of any packages you installed from pub.dev
-2. [migrate](#migrate) all of your source code to use sound null safety.
+2. [migrate](#migrate) all your source code to use sound null safety.
 
-Dart 3 can be found in the stable channels for Dart and Flutter.
-To learn more, check out [the download page][] for details.
+You can find Dart 3 in the stable channels for Dart and Flutter.
+To learn more, review [the download page][] for details.
 To test your code for Dart 3 compatibility, use Dart 3 or later.
 
 ```terminal
@@ -123,7 +122,7 @@ $ dart pub get / flutter pub get     # this should resolve without issues
 $ dart analyze / flutter analyze     # this should pass without errors
 ```
 
-If the `pub get` step fails, check the [status of the dependencies][].
+If the `pub get` step fails, verify the [status of the dependencies][].
 
 If the `analyze` step fails, update your code to resolve the issues
 listed by the analyzer.
@@ -134,7 +133,7 @@ listed by the analyzer.
 ## Dart 2.x and null safety {#enable-null-safety}
 
 From Dart 2.12 to 2.19, you need to enable null safety.
-You cannot use null safety in SDK versions earlier than Dart 2.12.
+You can't use null safety in SDK versions earlier than Dart 2.12.
 
 <a id="constraints"></a>
 To enable sound null safety, set the
@@ -170,11 +169,11 @@ $ dart migrate
 ```
 
 To learn how to migrate your code to null safety,
-check out the [migration guide][].
+review the [migration guide][].
 
 ## Where to learn more
 
-To learn more about null safety, check out the following resources:
+To learn more about null safety, review the following resources:
 
 * [Null safety codelab][]
 * [Understanding null safety][]
@@ -190,4 +189,3 @@ To learn more about null safety, check out the following resources:
 [#34233]: https://github.com/dart-lang/sdk/issues/34233
 [#49529]: https://github.com/dart-lang/sdk/issues/49529
 [#2357]: https://github.com/dart-lang/language/issues/2357
-

src/resources/index.md

@@ -6,7 +6,6 @@ toc: false
 
 Check out the following Dart language resources:
 
-
 <div class="card-grid">
   <div class="card">
     <h3><a href="/resources/books">Books</a></h3>

styles/Google/Contractions.yml

@@ -1,5 +1,5 @@
 extends: substitution
-message: "Feel free to use '%s' instead of '%s'."
+message: "Use '%s' instead of '%s'."
 link: 'https://developers.google.com/style/contractions'
 level: suggestion
 ignorecase: true

styles/Google/Exclamation.yml

@@ -3,5 +3,7 @@ message: "Don't use exclamation points in text."
 link: 'https://developers.google.com/style/exclamation-points'
 nonword: true
 level: error
+action:
+  name: remove
 tokens:
-  - '\w!(?:\s|$)'
+  - '\w+!(?:\s|$)'

styles/Google/GenderBias.yml

@@ -3,6 +3,8 @@ message: "Consider using '%s' instead of '%s'."
 link: 'https://developers.google.com/style/inclusive-documentation'
 ignorecase: true
 level: error
+action:
+  name: replace
 swap:
   (?:alumna|alumnus):          graduate
   (?:alumnae|alumni):          graduates

styles/Google/Headings.yml

@@ -1,15 +1,14 @@
 extends: capitalization
 message: "'%s' should use sentence-style capitalization."
-link: 'https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings'
+link: "https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings"
 level: warning
 scope: heading
 match: $sentence
 indicators:
-  - ':'
+  - ":"
 exceptions:
   - Azure
   - CLI
-  - Code
   - Cosmos
   - Docker
   - Emmet

styles/Google/Latin.yml

@@ -7,5 +7,5 @@ nonword: true
 action:
   name: replace
 swap:
-  '\b(?:eg|e\.g\.)[\s,]': for example
-  '\b(?:ie|i\.e\.)[\s,]': that is
+  '\b(?:eg|e\.g\.)(?=[\s,;])': for example
+  '\b(?:ie|i\.e\.)(?=[\s,;])': that is

styles/Google/Passive.yml

@@ -30,6 +30,7 @@ tokens:
   - built
   - burnt
   - burst
+  - by
   - cast
   - caught
   - chosen

styles/Google/Spacing.yml

@@ -3,6 +3,8 @@ message: "'%s' should have one space."
 link: 'https://developers.google.com/style/sentence-spacing'
 level: error
 nonword: true
+action:
+  name: remove
 tokens:
   - '[a-z][.?!] {2,}[A-Z]'
   - '[a-z][.?!][A-Z]'

styles/Google/Spelling.yml

@@ -5,4 +5,6 @@ ignorecase: true
 level: warning
 tokens:
   - '(?:\w+)nised?'
-  - '(?:\w+)logue'
+  - 'colour'
+  - 'labour'
+  - 'centre'

styles/Google/Units.yml

@@ -1,8 +1,8 @@
 extends: existence
 message: "Put a nonbreaking space between the number and the unit in '%s'."
-link: 'https://developers.google.com/style/units-of-measure'
+link: "https://developers.google.com/style/units-of-measure"
 nonword: true
 level: error
 tokens:
-  - \d+(?:B|kB|MB|GB|TB)
-  - \d+(?:ns|ms|s|min|h|d)
+  - \b\d+(?:B|kB|MB|GB|TB)
+  - \b\d+(?:ns|ms|s|min|h|d)