coder · nickvigilante · Jul 8, 2026 · Jun 25, 2026 · Jun 26, 2026 · Jun 26, 2026
diff --git a/docs/.style/style-guide/README.md b/docs/.style/style-guide/README.md
@@ -2,16 +2,16 @@
 
 This is the canonical prose style guide for the Coder documentation.
 It tells you *how* to write the words that go in the docs.
-For decisions about what belongs in the docs and what does not, refer to [`content-guidelines.md`](../content-guidelines.md).
+For decisions about what belongs in the docs and what doesn't, refer to [`content-guidelines.md`](../content-guidelines.md).
 
-Each rule on the pages below is a policy decision the Coder docs team has made.
+Each rule on the linked pages is a policy decision the Coder docs team has made.
 Where a Vale rule already enforces the policy, the rule name is listed in a parenthetical so you can reproduce the warning locally.
 Where the rule is documentation-only, the parenthetical says so.
 The doctrine for adding Vale rules lives in [`README.md`](../README.md).
 
 ## How to use this guide
 
-- **Contributors**: read the section that matches what you are writing.
+- **Contributors**: read the section that matches what you're writing.
   Each rule includes a brief rationale and **Do** / **Don't** examples.
 - **Reviewers**: cite the section in a review comment.
   Reviews are easier when the guidance lives in one place.
@@ -40,9 +40,9 @@ The style guide subpages dogfood them so contributors can see the rules in actio
 
 Source lines in Coder documentation follow a one-sentence-per-line policy.
 Each sentence sits on its own Markdown source line.
-Sentences are not split across lines, and lines do not wrap to a fixed column width.
+Sentences aren't split across lines, and lines don't wrap to a fixed column width.
 
-The rendered Markdown joins lines inside a paragraph back together, so the source line breaks do not appear in the rendered output.
+The rendered Markdown joins lines inside a paragraph back together, so the source line breaks don't appear in the rendered output.
 Reviewers reading the diff do encounter them, and they make diffs land cleanly at the sentence level.
 
 `markdownlint`'s `MD013` (line length) is already disabled, so the convention is editorial.
@@ -55,12 +55,12 @@ Much of the existing prose still wraps to a fixed column width or runs on a sing
 The convention is adopted incrementally.
 
 When a contributor edits any line inside a paragraph, the entire paragraph is reformatted to one sentence per line as part of the same edit.
-The contributor does not reformat surrounding paragraphs they did not otherwise touch.
+The contributor doesn't reformat surrounding paragraphs they didn't otherwise touch.
 
 For this rule, a bullet item, a numbered list entry, and a blockquote line are each their own paragraph.
 Headings, fenced code blocks, and tables are out of scope: headings are single lines by convention, code blocks render their source verbatim, and table rows are governed by `markdown-table-formatter`.
 
-### The style guide does not use "see" for navigation
+### The style guide doesn't use "see" for navigation
 
 The [Word choice page](./word-choice.md) bans "see" as a navigational verb across all docs.
 The style guide itself follows the rule: "refer to" for formal cross-references, "check out" for informal pointers in tutorial-style passages, "visit" for external URLs.
@@ -69,7 +69,7 @@ Reserve "see" for the rare case where the prose describes what a reader observes
 ## Vale enforcement
 
 The repo-root `.vale.ini` loads only the Coder rule package by default.
-Third-party rules from Google, alex, and write-good are not enabled until a per-rule PR brings each back in.
+Third-party rules from Google, alex, and write-good aren't enabled until a per-rule PR brings each back in.
 
 Each enabled rule lands via a dedicated PR that:
 
@@ -93,13 +93,13 @@ Run `make lint/prose` to reproduce the baseline locally.
 
 A public-facing prose summary lives today at [`docs/about/contributing/documentation.md`](../../about/contributing/documentation.md).
 A follow-up PR will redirect that page to this guide.
-Until then, follow the public summary for anything the subpages of this guide do not cover.
+Until then, follow the public summary for anything the subpages of this guide don't cover.
 New prose rules land here.
 The public page is frozen pending the redirect.
 
 ## Third-party references
 
-When this guide does not cover something, consult:
+When this guide doesn't cover something, consult:
 
 | Type of guidance         | Reference                                                                               |
 |--------------------------|-----------------------------------------------------------------------------------------|

diff --git a/docs/.style/style-guide/accessibility-and-inclusion.md b/docs/.style/style-guide/accessibility-and-inclusion.md
@@ -1,6 +1,6 @@
 # Accessibility and inclusion
 
-The Coder documentation aims for [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA conformance as a minimum, with Level AAA as a stretch goal where it does not sacrifice clarity.
+The Coder documentation aims for [WCAG 2.1](https://www.w3.org/TR/WCAG21/) Level AA conformance as a minimum, with Level AAA as a stretch goal where it doesn't sacrifice clarity.
 The rules on this page support that target.
 They cover heading structure, inclusive language, link text, images, plain English for international readers, page descriptions, and reading level.
 
@@ -10,14 +10,14 @@ They cover heading structure, inclusive language, link text, images, plain Engli
 ## Heading structure and placement
 
 Each page has exactly one H1.
-The H1 is the page title and appears once at the top of the page.
+The H1 is the page title and appears once at the beginning of the page.
 Subsequent headings descend by one level at a time.
 A page goes H1, then H2, then H3.
-A page does not jump from H2 to H4.
+A page doesn't jump from H2 to H4.
 
 Each heading is followed by at least one paragraph (or other content block) before the next heading.
 A bare H2 followed immediately by an H3 with no prose in between reads as a broken document outline, and SEO crawlers flag the pattern as a potential site error.
-If a parent heading does not yet have introductory content, write a short paragraph that frames what the section covers before the subheadings.
+If a parent heading doesn't yet have introductory content, write a short paragraph that frames what the section covers before the subheadings.
 
 The rule is a [WCAG 2.1 Level A](https://www.w3.org/TR/WCAG21/#info-and-relationships) requirement: assistive technology relies on heading levels to convey document structure.
 Skipping a level breaks the outline.
@@ -28,12 +28,12 @@ Skipping a level breaks the outline.
 # Configure your workspace
 
 This page walks through the configuration options exposed on a Coder workspace.
-The sections below cover SSH access and environment variables.
+The following sections cover SSH access and environment variables.
 
 ## Set up SSH access
 
 SSH access uses the agent that runs inside your workspace.
-Two client setups are documented below.
+Two client setups are documented in the following sections.
 
 ### Connect through JetBrains Toolbox
 
@@ -123,19 +123,19 @@ Screen readers announce link text out of context too, which is the [WCAG 2.1 Lev
 
 Every image declares descriptive alt text.
 The alt text describes what the image shows or what purpose it serves.
-It is not a caption.
-Captions go below the image in a `<small>` tag.
+It isn't a caption.
+Captions follow the image in a `<small>` tag.
 
 Aim for one or two sentences that convey the same information a sighted reader would extract from the image.
 Lead with the subject, not "An image of" or "A screenshot showing".
 
 ```markdown
 ![Template Insights dashboard with weekly active users and connection latency charts](../../images/admin/templates/template-insights.png)
 
-<small>The Template Insights dashboard. Active users in the left panel; connection latency in the right panel.</small>
+<small>The Template Insights dashboard with active-user and connection-latency widgets.</small>
 ```
 
-For complex diagrams that cannot be summarized in alt text, provide a longer description in the body of the page and reference it from the alt text.
+For complex diagrams that can't be summarized in alt text, provide a longer description in the body of the page and reference it from the alt text.
 
 *Enforced by `markdownlint` rule `MD045` for the alt-text-required requirement.*
 
@@ -155,14 +155,57 @@ When in doubt, write descriptive alt text.
 *Documentation-only.
 No Vale rule.*
 
+## Directional language
+
+Screen-reader users navigate documents linearly and don't experience the visual layout.
+Phrases like "see below", "above the table", or "the menu on the left" lose meaning when the reader can't see where elements sit on the page.
+Sighted readers also benefit from semantic references when the page gets restructured or they jump in through an anchor link.
+
+Refer to content by section heading, by document order (`the previous section`, `the following section`), or by anchor link.
+Refer to UI elements by their label, not by their position on the screen.
+
+**Do**:
+
+> See the [Latin abbreviations rule](#latin-abbreviations) for the comma convention.
+>
+> Add a `<small>` caption after the image.
+>
+> Open the **Workspaces** sidebar to switch templates.
+
+**Don't**:
+
+> See the table below for the comma convention.
+>
+> Add a `<small>` caption underneath the image.
+>
+> Open the menu on the left to switch templates.
+
+Common replacements:
+
+| Avoid                        | Prefer                                                  |
+|------------------------------|---------------------------------------------------------|
+| see below                    | see the following section, see the `[Section](#anchor)` |
+| see above                    | see the previous section, see earlier                   |
+| top of the page              | beginning of the page                                   |
+| bottom of the page           | end of the page                                         |
+| the menu on the left         | the **Sidebar** menu                                    |
+| the right side of the screen | the **Details** panel                                   |
+| scroll down                  | scroll to the `[Section](#anchor)`, scroll to the end   |
+
+The rule covers prose.
+Idiomatic stack metaphors like "built on top of Terraform" and phrasal verbs like "set up", "back up", "log in", and "shut down" aren't directional and stay as-is.
+
+*Documentation-only.
+No Vale rule.*
+
 ## Plain English for international readers
 
-Keep prose accessible to readers whose first language is not English.
+Keep prose accessible to readers whose first language isn't English.
 Two patterns add friction for non-native speakers without adding meaning, so the guide bans them:
 
 ### Avoid idioms and figurative language
 
-Idioms (`under the weather`, `ballpark figure`, `get the ball rolling`, `at the eleventh hour`) and figurative language (`unleash`, `supercharge`, `dive in`, `out of the box`) rely on cultural context that does not translate.
+Idioms (`under the weather`, `ballpark figure`, `get the ball rolling`, `at the eleventh hour`) and figurative language (`unleash`, `supercharge`, `dive in`, `out of the box`) rely on cultural context that doesn't translate.
 They also rarely add precision.
 Replace them with the literal meaning.
 
@@ -190,13 +233,13 @@ Planned Vale rule `Coder.Idioms`.*
 The following Latin abbreviations are fine in Coder docs.
 Use them when they fit the sentence; the English equivalent is also fine.
 
-| Abbreviation | Meaning                                        | Notes                                                                          |
-|--------------|------------------------------------------------|--------------------------------------------------------------------------------|
-| `e.g.`       | for example                                    | Followed by a comma. Prefer parentheses around the clause, as described below. |
-| `i.e.`       | that is                                        | Followed by a comma. Prefer parentheses around the clause, as described below. |
-| `etc.`       | and so on                                      | Closes a list. The Oxford comma applies before it: `apples, oranges, etc.`     |
-| `vs.`        | versus, against, as opposed to, in contrast to | No comma. Example: `coder server vs. coder agent`.                             |
-| `et al.`     | and others                                     | Citation contexts only. Follow the citation style's punctuation rules.         |
+| Abbreviation | Meaning                                        | Notes                                                                      |
+|--------------|------------------------------------------------|----------------------------------------------------------------------------|
+| `e.g.`       | for example                                    | Followed by a comma. Prefer parentheses around the clause.                 |
+| `i.e.`       | that is                                        | Followed by a comma. Prefer parentheses around the clause.                 |
+| `etc.`       | and so on                                      | Closes a list. The Oxford comma applies before it: `apples, oranges, etc.` |
+| `vs.`        | versus, against, as opposed to, in contrast to | No comma. Example: `coder server vs. coder agent`.                         |
+| `et al.`     | and others                                     | Citation contexts only. Follow the citation style's punctuation rules.     |
 
 **Prefer parentheses around `e.g.` and `i.e.` clauses.** The parentheses make the sentence structure obvious and avoid a cascade of commas around the abbreviation.
 
@@ -241,7 +284,7 @@ The same rule applies if `e.g.` or `i.e.` ever sits at the end of a sentence, th
 >
 > The protocol is described by Smith et al. (2020).
 
-**Less common Latin abbreviations are not allowed.** Latin abbreviations beyond the five in the table, such as `a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, and `ibid.`, are unfamiliar to many readers and easy to misuse.
+**Less common Latin abbreviations aren't allowed.** Latin abbreviations beyond the five in the table, such as `a priori`, `q.v.`, `viz.`, `n.b.`, `cf.`, and `ibid.`, are unfamiliar to many readers and easy to misuse.
 Replace them with plain English.
 
 **Don't**:
@@ -274,7 +317,7 @@ A page's H1 and its sidebar title serve different jobs and may diverge.
   It fits the limited horizontal space of the sidebar and reads fast when the reader is scanning a tree of dozens of pages.
   The Coder docs site reads the sidebar title from the `title` field in [`docs/manifest.json`](../../manifest.json).
 
-The two must each stand alone, but they do not need to be identical.
+The two must each stand alone, but they don't need to be identical.
 Breadcrumb depth gives one layer of context for free.
 The sidebar title can drop redundancy that the parent breadcrumbs already imply.
 
@@ -283,7 +326,7 @@ A page reachable through **Administration** > **Authentication** > **Google** ha
 The sidebar title can be `Google` alone, and the H1 can be `Configure Google authentication with Coder`.
 Both labels stand alone in their own context.
 
-When the H1 and the sidebar title coincide (often the case for short-titled pages), that is fine.
+When the H1 and the sidebar title coincide (often the case for short-titled pages), that's fine.
 When they diverge, the divergence is intentional and serves the reader.
 The same pattern is common in mature docs sites.
 AWS, Microsoft Learn, and GitHub Docs all pair task-focused H1s with shorter noun-focused sidebar titles.
@@ -306,7 +349,7 @@ AWS, Microsoft Learn, and GitHub Docs all pair task-focused H1s with shorter nou
 
 The first **Don't** row uses the full H1 as the sidebar title.
 The sidebar title is redundant with the parent breadcrumbs and crowds the navigation tree.
-The second row has a sidebar title that does not stand alone.
+The second row has a sidebar title that doesn't stand alone.
 The third row has a sidebar title that tells the reader nothing.
 
 *Documentation-only.
@@ -329,7 +372,7 @@ The manifest maps each page to a `title` and a `description`:
 A good description:
 
 - States what the page covers in one sentence.
-- Stays under roughly 160 characters so search engines do not truncate it.
+- Stays under roughly 160 characters so search engines don't truncate it.
 - Avoids marketing language and superlatives.
 - Reads as a complete sentence.
 
@@ -350,9 +393,9 @@ A good description:
 ```
 
 The short description tells the reader nothing.
-The marketing description does not survive truncation and adds no information.
+The marketing description doesn't survive truncation and adds no information.
 
-If a page does not yet have a description in the manifest, add one in the same PR that touches the page.
+If a page doesn't yet have a description in the manifest, add one in the same PR that touches the page.
 
 *Documentation-only.
 No Vale rule.*
@@ -378,8 +421,8 @@ The criterion is satisfied either by writing at the lower-secondary reading leve
 Coder docs write at the target reading level directly.
 
 Editors that surface a grade-level score (Hemingway, Vale's `write-good.Reading`) are a useful spot check.
-The grade level is not a hard ceiling.
-A reference page that requires technical vocabulary will read higher than a tutorial, and that is correct.
+The grade level isn't a hard ceiling.
+A reference page that requires technical vocabulary will read higher than a tutorial, and that's correct.
 
 *Documentation-only.
 No Vale rule wired.*