Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs(docs/.style/style-guide): add directional-language and contractions rules - #26729

Merged
nickvigilante merged 3 commits into
mainfrom
vigilante/docs-462-add-screen-reader-aware-directional-language-rule-and-sweep
Jul 8, 2026
Merged

docs(docs/.style/style-guide): add directional-language and contractions rules#26729
nickvigilante merged 3 commits into
mainfrom
vigilante/docs-462-add-screen-reader-aware-directional-language-rule-and-sweep

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Jun 25, 2026

Copy link
Copy Markdown
Contributor

Adds two new accessibility-and-voice rules to the style guide.

Directional language (docs/.style/style-guide/accessibility-and-inclusion.md). Screen-reader users navigate documents linearly and cannot follow spatial references like "see below" or "the menu on the left". The rule prescribes anchor links, section headings, document order ("the previous section", "the following section"), and named UI elements instead. A replacement table covers the common cases.

Contractions are the default (docs/.style/style-guide/voice-and-tone.md). Prefer contractions in body prose for the same reason the docs use second person and present tense. Three exceptions: auxiliary contractions (you'd, there's, it's, we'd, they're) need an explicit complement and cannot end a sentence; contractions join exactly two words (no you'd've or wouldn't've); spell out for emphasis and high-stakes operations like deletion or data loss (do not, cannot, will not).

The PR also sweeps the existing style-guide subpages so the existing prose comply with both rules.

Resolves DOCS-462.

Directional-language sweep targets
File Change
docs/.style/style-guide/README.md "pages below" becomes "linked pages"
docs/.style/style-guide/accessibility-and-inclusion.md "top of the page" becomes "beginning of the page". Captions "follow" instead of "go below". Latin abbreviation table cells drop "as described below". Sample captions name widgets instead of panel positions.
docs/.style/style-guide/audience-and-scope.md Don't example rewritten without "below". "Above the first paragraph" becomes "before the first paragraph". "At the top of the page" becomes "at the beginning of the page".
docs/.style/style-guide/capitalization-and-punctuation.md "Exceptions above" becomes "exceptions listed earlier".
docs/.style/style-guide/formatting.md Captions "follow" instead of "go below". Sample captions renamed by widget. Don't example "as shown above" becomes "as shown in the screenshot".
docs/.style/style-guide/numbers-units-and-dates.md "10th and up" becomes "10th and higher".

Idiomatic stack metaphors like "built on top of Terraform" and phrasal verbs like "set up", "back up", "log in", and "shut down" are explicitly carved out as not directional and stay as-is.

Contractions rule scope

The rule lands as ## Contractions are the default in voice-and-tone.md, placed between Present tense by default and Trailing prepositions are a judgment call because all three rules sit in the natural-phrasing cluster.

The sweep applies the rule across all eight style-guide subpages: 76 lines updated where the spelled-out form (does not, is not, cannot, you have, there is, that is) reads more naturally as a contraction.

Skipped:

  • Don't blocks inside the contractions rule that intentionally demonstrate the wrong form.
  • Do blocks inside the emphasis sub-rule that intentionally model do not, cannot, and will not for high-stakes operations.
  • The Churchill joke inside the trailing-prepositions Don't blocks.
  • The "that is" dictionary definition of i.e. in the Latin abbreviations table.
  • may not (no contraction in modern English).
  • that has relative clauses where 's could read as possessive.
Lints
  • make lint/markdown: 0 errors across 495 files.
  • make lint/prose: only the pre-existing intentional [Demo] annotations in docs/.style/_vale-annotation-demo.md fire.

Filed via Coder Agents on Nick's behalf.

@linear-code

linear-code Bot commented Jun 25, 2026

Copy link
Copy Markdown

DOCS-462

…p existing pages

Add a new accessibility-and-inclusion rule that warns against spatial references like "see below", "above", or "the menu on the left", which screen-reader users navigating linearly cannot interpret. The rule prescribes anchor links, section headings, document order ("the previous section", "the following section"), and named UI elements instead. A replacement table covers the common cases.

Sweep the six style-guide subpages so the existing rule examples and prose comply. Captions "go below" become captions that "follow". "At the top of the page" becomes "at the beginning of the page". "As described below" inside the Latin abbreviations table dropped; the next paragraph supplies the detail. "10th and up" becomes "10th and higher". "As shown above" inside the screenshot-as-content Don't example becomes "as shown in the screenshot".

Idiomatic stack metaphors ("built on top of Terraform") and phrasal verbs ("set up", "back up", "log in", "shut down") are explicitly carved out and stay as-is.

Lints clean: make lint/markdown and make lint/prose.
@nickvigilante nickvigilante changed the title docs(.style/style-guide): add directional-language rule and sweep existing pages docs(docs/.style/style-guide): add directional-language rule and sweep existing pages Jun 25, 2026
@nickvigilante
nickvigilante force-pushed the vigilante/docs-462-add-screen-reader-aware-directional-language-rule-and-sweep branch from 6302d57 to 90d903d Compare June 25, 2026 21:34
Add a new voice-and-tone rule that prefers contractions in body prose for the same reason the docs use second person and present tense: the prose should read like a person talking to the reader.

Three exceptions. (1) Auxiliary contractions like 'you'd', 'there's', 'it's', 'we'd', and 'they're' cannot end a sentence because the elided verb form goes missing with them. Negation contractions like 'don't', 'won't', and 'can't' end sentences fine. (2) Contractions join exactly two words. Triple-word contractions like 'you'd've' and 'wouldn't've' get expanded to one of two forms ('you would've' or 'you'd have') depending on which reads more naturally. (3) Data loss, security warnings, and irreversible operations get the full visual weight of 'do not', 'cannot', and 'will not'.

Section lands between 'Present tense by default' and 'Trailing prepositions are a judgment call' because all three rules sit in the natural-phrasing cluster of voice-and-tone.

Lints clean: make lint/markdown and make lint/prose.
@nickvigilante nickvigilante changed the title docs(docs/.style/style-guide): add directional-language rule and sweep existing pages docs(docs/.style/style-guide): add directional-language and contractions rules Jun 26, 2026
…rtunities

Apply the contractions rule across the existing style-guide subpages. 76 lines updated where the spelled-out form ('does not', 'is not', 'cannot', 'you have', 'there is', 'that is') reads more naturally as a contraction.

Skipped: Don't blocks inside the contractions rule that intentionally demonstrate the wrong form; Do blocks inside the emphasis sub-rule that intentionally model 'do not', 'cannot', and 'will not' for high-stakes operations; the Churchill joke inside the trailing-prepositions Don't blocks; and the 'that is' dictionary definition of i.e. in the Latin abbreviations table.

Skipped 'may not' (no contraction in modern English), 'must not' (zero matches), and 'that has' relative clauses where ''s' could read as possessive.

Lints clean: make lint/markdown and make lint/prose.
@nickvigilante
nickvigilante marked this pull request as ready for review June 26, 2026 19:42
@nickvigilante
nickvigilante requested a review from bpmct June 26, 2026 19:42
@github-actions github-actions Bot added the stale This issue is like stale bread. label Jul 5, 2026
@nickvigilante nickvigilante removed the stale This issue is like stale bread. label Jul 8, 2026
@nickvigilante
nickvigilante merged commit 83cb587 into main Jul 8, 2026
43 of 44 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-462-add-screen-reader-aware-directional-language-rule-and-sweep branch July 8, 2026 16:05
@github-actions github-actions Bot locked and limited conversation to collaborators Jul 8, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants