docs(project): add support for the alex linter (#4396)

* chore(project): add alex dependency

* chore(cli): add lint:docs task to ci-check

* docs(alex): fix content violations

* Update docs/guides/accessibility.md

* Update docs/guides/endgame.md

* chore(project): add alexignore file for generated sassdoc files

.alexignore

@@ -0,0 +1,2 @@
+# Ignore generated SassDoc files
+**/docs/sass.md

docs/developer-handbook.md

@@ -212,7 +212,7 @@ _Parts of this section are duplicated from
 [Angular's commit conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines)_.
 
 Each commit message consists of a **header**, a **body** and a **footer**. The
-header has a special format that includes a type, a scope and a subject:
+header has a specific format that includes a type, a scope and a subject:
 
 ```git
 <type>(<scope>): <subject>
@@ -259,10 +259,14 @@ The subject contains a succinct description of the change:
 
 ### Body
 
+<!-- alex disable just -->
+
 Just as in the subject, use the imperative, present tense: "change" not
 "changed" nor "changes". The body should include the motivation for the change
 and contrast this with previous behavior.
 
+<!-- alex enable just -->
+
 ### Footer
 
 The footer should contain any information about Breaking Changes.
@@ -496,8 +500,8 @@ There are two ways to define markups for components and their variants:
 
 ### Defining markup with no conditional or data interpolations
 
-Defining markup with no conditional or data interpolation is as easy as adding a
-`.hbs` file to the component directory. No `.config.js` file in the component
+To define markup with no conditional or data interpolation you will need to add
+a `.hbs` file to the component directory. No `.config.js` file in the component
 directory is required in this case. One thing to note is that If there is a
 `.hbs` file whose basename is exactly the same as the component name, other
 `.hbs` files has to be in `componentname--variantname.hbs` format.
@@ -596,8 +600,8 @@ compile and update Storybook you can run the following command in the
 yarn gulp watch -s
 ```
 
-This will execute the `watch` command in `gulpfile.js`. As a result, whenever
-you make a change to the project styles it will automatically copy over into the
+This will run the `watch` command in `gulpfile.js`. As a result, whenever you
+make a change to the project styles it will automatically copy over into the
 `scss` folder which Storybook uses in `carbon-components-angular`.
 
 ### Pointing NPM dependency of `carbon-components` right to the source code
@@ -749,7 +753,7 @@ code at that point in time.
 
 #### How do I install a dependency?
 
-When installing a dependency, you can just do `yarn add <dependency-name>` as
+When installing a dependency, you can run `yarn add <dependency-name>` as
 normal. The only difference now is that you also will check in the corresponding
 tarball entry in `.yarn/offline-mirror` as well so that we don't have to fetch
 this dependency from the live registry during Continuous Integration builds.

docs/guides/accessibility.md

@@ -1,3 +1,5 @@
+<!-- alex disable failure -->
+
 # Accessibility
 
 <!-- prettier-ignore-start -->
@@ -73,8 +75,8 @@ positives when testing exclusively on a component. Typically we're not auditing
 a webpage or a website as a whole, but a single component in isolation -- sadly
 this was not DAP's intended purpose and so it throws a lot of false positive
 violations that you'll first need to sift through and ignore if we're going to
-be keeping and recording this audit. If you're just testing while you develop or
-before you push a PR, feel free to just disregard them.
+be keeping and recording this audit. If you're only testing while you develop or
+before you push a PR, feel free to disregard them.
 
 If the component fails or has a violation an issue should be made so that
 someone can fix the problem. Feel free to include in the issue any relevant
@@ -148,13 +150,17 @@ using only your keyboard in the manner described. Integrating this test
 throughout each stage of development will save you the pain of retro-fitting a
 component with the necessary keyboard functionality.
 
-### Screen Magnifier testing🔎
+### Screen magnifier testing🔎
+
+<!-- alex disable his -->
 
 (Credit to Frederick Creemers
 [excellent article](https://dev.to/_bigblind/how-to-make-your-website-accessible-to-people-who-use-a-screen-magnifier)
 talking about his experience as a visually impaired screen magnification user on
 the web.)
 
+<!-- alex enable his -->
+
 A user with a screen magnifier views web content on a component by component
 basis through a 2x, 4x, or 8x (etc) zoomed in box. Two things become very
 important when using a screen magnifier -- context and component permanence. We
@@ -205,10 +211,10 @@ consistency's sake we'll use DAP on the
 Head over to the page and hit `cmd-option-c` to open up your dev tools. DAP is
 tucked away inside a drop down menu inside a panel. From the default Elements
 panel hit the >> icon below the X on the far right. You should see `DAP`. Click
-that to fire up DAP for this page.
+that to open up DAP for this page.
 
 _Be Warned: You can only run DAP with internal IBM rulesets if you're connected
-to W3. On an IBM campus this isn't a problem, but if you're abroad fire up the
+to W3. On an IBM campus this isn't a problem, but if you're abroad open the
 Cisco AnyConnect Secure Mobility Client._
 
 Hit the play button and wait for the scan to finish. **We've got violations!**.

docs/guides/building-an-icon-library.md

@@ -34,7 +34,7 @@ After you've received the green light, then you're ready to get started!
 ## Getting Started
 
 The main package that exports all icon information is
-[`@carbon/icons`](/packages/icons). This package hosts all of the source SVG
+[`@carbon/icons`](/packages/icons). This package contains all of the source SVG
 assets, in addition to exporting the following assets:
 
 - Optimized SVG assets from source files
@@ -58,7 +58,7 @@ determining how to best architect their implementation:
     `<Icon name="icon-name">` component given that we could not tree-shake
     `@carbon/icons` descriptors
   - A system could support `<Icon icon={descriptor} />`, however this would
-    require a user to install two dependencies versus just your icon library
+    require a user to install two dependencies versus only your icon library
 - Minimize the amount of runtime logic that has to be run. As a result, prefer
   generating markup statically from SVG data versus using the data at runtime to
   build up the SVG markup

docs/guides/colors.md

@@ -1,3 +1,5 @@
+<!-- alex disable colors -->
+
 # Colors
 
 <!-- prettier-ignore-start -->

docs/guides/endgame.md

@@ -1,3 +1,5 @@
+<!-- alex disable black -->
+
 # Endgame
 
 <!-- prettier-ignore-start -->
@@ -472,9 +474,9 @@ already exist in the project. These updates are reserved for
 
 4. Once that's done, you should create a Pull Request in Draft state and make
    sure **not** to merge it. Our goal with the Pull Request is to do a final
-   sanity check for CI checks, verify preview links work as expected, and get
-   final reviews from the endgame team for the release. _Note: Make sure to
-   specify which packages are being updated for your reviewers._
+   check for CI checks, verify preview links work as expected, and get final
+   reviews from the endgame team for the release. _Note: Make sure to specify
+   which packages are being updated for your reviewers._
 
 5. Once everything is green, review the pull request. Make sure there are no
    commits labeled `feat` as the patch release should only be for bug fixes,
@@ -499,8 +501,7 @@ already exist in the project. These updates are reserved for
    npm dist-tag add package-name@X.Y.Z latest
    ```
 
-   For example, if you just released `10.6.1` under `next`, this would look
-   like:
+   For example, if you released `10.6.1` under `next`, this would look like:
 
    ```bash
    npm dist-tag add carbon-components@10.6.1 latest
@@ -509,10 +510,10 @@ already exist in the project. These updates are reserved for
 8. Manually check to see that the `latest` tags were updated for the packages
    correctly by going to [`npm`](https://www.npmjs.com), searching the packages,
    viewing the versions and making sure the `latest` version matches the version
-   you just released.
+   you released.
 
-9. After publishing to latest, create a tag for the version you just released
-   and push it to upstream by running:
+9. After publishing to latest, create a tag for the version you released and
+   push it to upstream by running:
 
    ```bash
    git tag -a vX.Y.Z -m "vX.Y.Z"
@@ -712,9 +713,9 @@ git commit -m 'chore(release): update package versions'
 ```
 
 Once that's done, you should create a Pull Request in Draft state and make sure
-**not** to merge it. Our goal with the Pull Request is to do a final sanity
-check for CI checks, verify preview links work as expected, and get final
-reviews from the endgame team for the release.
+**not** to merge it. Our goal with the Pull Request is to do a check for CI
+checks, verify preview links work as expected, and get final reviews from the
+endgame team for the release.
 
 Once everything is green and your Pull Request has been reviewed, you should
 **close** the draft Pull Request. On your machine, you should then follow the
@@ -729,8 +730,8 @@ following steps to release:
 - If everything looks good to go, then you should go through each of the
   packages and add the `latest` tag using the command:
   `npm dist-tag add package-name@X.Y.Z latest`
-- After publishing to latest, create a tag for the version you just released and
-  push it to upstream by running:
+- After publishing to latest, create a tag for the version you released and push
+  it to upstream by running:
 
   ```bash
   git tag -a vX.Y.Z -m "vX.Y.Z"
@@ -769,7 +770,7 @@ following steps to release:
 ### Release candidate releases
 
 ​ Before our minor releases, we cut release candidates a week in advance to
-sanity check our code. ​
+check our code. ​
 
 #### Publishing steps
 
@@ -794,7 +795,7 @@ sanity check our code. ​
 6. Manually check to see that the `next` tag was updated for the packages
    correctly by going to [`npm`](https://www.npmjs.com), searching the packages,
    viewing the versions and making sure the `next` version matches the version
-   you just released.
+   you released.
 
 ### Minor releases
 
@@ -832,7 +833,7 @@ can be released on-demand in specific circumstances.
 
 3. After the package versions have been created, you'll be prompted
    `The next step will be to manually create a Pull Request for this branch`.
-   Simply push your changes and open the PR. Be sure your commit message reads
+   Push your changes and open the PR. Be sure your commit message reads
    `chore(release): update package versions`
 4. Once your PR is approved and merged, checkout `master`, pull the latest
    upstream and run:
@@ -853,7 +854,7 @@ can be released on-demand in specific circumstances.
 7. Manually check to see that the `next` tag was updated for the packages
    correctly by going to [`npm`](https://www.npmjs.com), searching the packages,
    viewing the versions and making sure the `next` version matches the version
-   you just released.
+   you released.
 
 8. When you're ready to update `latest`, run
    `npm dist-tag add package-name@X.Y.Z latest` for each of the updated
@@ -876,10 +877,10 @@ can be released on-demand in specific circumstances.
 9. Like before, manually check to see that the `latest` tags were updated for
    the packages correctly by going to [`npm`](https://www.npmjs.com), searching
    the packages, viewing the versions and making sure the `latest` version
-   matches the version you just released.
+   matches the version you released.
 
-10. After publishing to latest, create a tag for the version you just released
-    and push it to upstream by running:
+10. After publishing to latest, create a tag for the version you released and
+    push it to upstream by running:
 
     ```bash
     git tag -a vX.Y.Z -m "vX.Y.Z"

docs/guides/ibm-plex.md

@@ -104,8 +104,7 @@ The following are the options for each of these sub-paths:
   - `Latin3`
   - `Pi`
 
-To get the hang of things, let's go through a couple of examples for various
-font families and formats.
+Let's go through a couple of examples for various font families and formats.
 
 <details>
 <summary>IBM Plex Arabic</summary>

docs/guides/sass.md

@@ -1,3 +1,5 @@
+<!-- alex disable color -->
+
 # Sass
 
 <!-- prettier-ignore-start -->

docs/guides/setup/design.md

@@ -1,3 +1,5 @@
+<!-- alex disable color -->
+
 # Design
 
 <!-- prettier-ignore-start -->
@@ -27,7 +29,7 @@
 ## Intro
 
 If you’re a designer looking to contribute, thanks so much for taking the time
-to learn. We really appreciate it! We also want to make it as easy as possible
+to learn. We really appreciate it! We also want to make it as simple as possible
 for you, so if you have any suggestions for improving this guide please let us
 know!
 

docs/guides/setup/windows.md

@@ -32,7 +32,7 @@ but can be unexpected.
     - `sudo umount /mnt/c`
     - `sudo mount -t drvfs C: /mnt/c -o metadata`
 12. Change directories into your projects folder
-    `cd /mnt/c/Users/{username}/projects` (Just an example, use whatever you'd
+    `cd /mnt/c/Users/{username}/projects` (Only an example, use whatever you'd
     like)
 13. Clone our repo
     `git clone https://github.com/carbon-design-system/carbon.git`

docs/guides/so-you're-going-on-vacation.md

@@ -35,6 +35,6 @@ you get back!
 - [ ] Delegate Pull Requests or Issue conversations that you're actively engaged
       in
 
-If you're on the hook for a review, or are actively engaging in an issue, make
+If you're responsible for a review, or are actively engaging in an issue, make
 sure to find an appropriate delegate while you're out so work isn't being
 blocked.

docs/guides/support.md

@@ -1,3 +1,5 @@
+<!-- alex disable failures -->
+
 # Carbon core support and maintenance
 
 <!-- prettier-ignore-start -->
@@ -58,7 +60,7 @@ ask them to do so. Typically you'll need at least a good description of the
 problem, a walkthrough of how to recreate the problem and a minimal test case to
 observe the problem happening. That last one can be a real sticking point, but
 there's lots of work to do and many many issues to triage — the onus is on them
-to clearly define the issue their having._
+to define the issue their having._
 
 ### Types of issues
 
@@ -140,7 +142,7 @@ future no label is needed because the issue should be closed)_.
 
 ### Other labels
 
-There are a whole host of labels that can help communicate the nature of an
+There is a large collection of labels that can help communicate the nature of an
 issue at a glance to developers and designers. Here's a few that you might add
 that can be particularly helpful:
 
@@ -165,8 +167,8 @@ can alert specific sub-teams on Carbon:
 
 Using any of these @'s in a comment will send notifications to members of those
 sub-teams. Typically a subject matter expert from that team will then take over.
-You can also just @username anyone Carbon's team if you specifically know
-someone who has experience with a particular component or issue.
+You can also @username anyone Carbon's team if you specifically know someone who
+has experience with a particular component or issue.
 
 ## Pull requests
 

docs/migration/10.x-color.md

@@ -1,3 +1,5 @@
+<!-- alex disable color -->
+
 # Colors
 
 <!-- prettier-ignore-start -->

docs/migration/10.x-themes.md

@@ -1,3 +1,5 @@
+<!-- alex disable color -->
+
 # Themes
 
 <!-- prettier-ignore-start -->

docs/on-windows-hcm-support.md

@@ -1,3 +1,5 @@
+<!-- alex disable colors -->
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
@@ -46,8 +48,8 @@ affordance enabled.
 
 ### Edge/Internet Explorer
 
-Microsoft's browsers Edge and Internet Explorer obviously have ideal support for
-WHCM applying a users chosen theme wholesale to the web content and allowing
+Microsoft's browsers Edge and Internet Explorer have ideal support for WHCM
+applying a users chosen theme wholesale to the web content and allowing
 developers to target problematic CSS generated graphics or SVGs via their
 extension and set safe fallbacks using CSS system colors.
 

docs/postmortems/2019-08-15-icons-angular.md

@@ -34,7 +34,7 @@ there was no prompt in the GitHub UI for a final review from the
 
 Since `v10.5.0` was recently released, we decided to use the `unpublish` feature
 of `npm` that is valid within 72hours of a release. Running this command
-subsequently unpublished the invalid build of `@carbon/icons-angular` and
+subsequently unpublished the broken build of `@carbon/icons-angular` and
 restored `v10.4.0` as the `latest` package for teams to consume.
 
 **Detection**
@@ -60,6 +60,8 @@ This issue was first reported by @cal-smith
 
 **Where we got lucky**
 
+<!-- alex disable period -->
+
 - We were still within the 72 hour time period required by `npm` for their
   `unpublish` feature to work