docs(a11y): use descriptive link text and inclusive wording - #4632
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
ShaneK
requested changes
Aug 12, 2026
| ``` | ||
|
|
||
| After the push is made, you will then see your commit under the `Commits` tab of the Appflow Dashboard. For more on this, take a look at the [Push a Commit](https://ionic.io/docs/appflow/quickstart/push) section inside the Appflow docs. | ||
| After the push is made, your commit appears under the `Commits` tab of the Appflow Dashboard. For more on this, take a look at the [Push a Commit](https://ionic.io/docs/appflow/quickstart/push) section inside the Appflow docs. |
Member
There was a problem hiding this comment.
Suggested change
| After the push is made, your commit appears under the `Commits` tab of the Appflow Dashboard. For more on this, take a look at the [Push a Commit](https://ionic.io/docs/appflow/quickstart/push) section inside the Appflow docs. | |
| After the push is made, your commit appears under the `Commits` tab of the Appflow Dashboard. For more information, refer to the [Push a Commit](https://ionic.io/docs/appflow/quickstart/push) section inside the Appflow docs. |
The first half of this sentence got the treatment, but "take a look at" in the second half is the same phrasing you're replacing everywhere else. The react and vue copies of this page have the identical line.
| ## Capacitor Setup | ||
|
|
||
| Capacitor is Ionic’s official app runtime that makes it easy to deploy web apps to native platforms like iOS, Android, and more. If you’ve used Cordova in the past, consider reading more about the differences [here](https://capacitorjs.com/docs/cordova#differences-between-capacitor-and-cordova). | ||
| Capacitor is Ionic’s official app runtime that makes it easy to deploy web apps to native platforms like iOS, Android, and more. If you’ve used Cordova in the past, consider reading more about the [differences between Capacitor and Cordova](https://capacitorjs.com/docs/cordova#differences-between-capacitor-and-cordova). |
Member
There was a problem hiding this comment.
Was leaving "easy to" here deliberate? You converted the [here] link on this same line, and this one reads more like marketing copy about Capacitor than minimizing the reader's work, so I can see the argument for keeping it. Same line in the react and vue copies.
Contributor
Author
There was a problem hiding this comment.
Not deliberate, minimizing language was outside this PR's scope.
| ## Layered Colors | ||
|
|
||
| Each color consists of the following properties: a `base`, `contrast`, `shade`, and `tint`. The `base` and `contrast` colors also require a `rgb` property which is the same color, just in <a href="https://developer.mozilla.org/en-US/docs/Glossary/RGB" target="_blank">rgb format</a>. See [The Alpha Problem](advanced.md#the-alpha-problem) for an explanation of why the `rgb` property is also needed. Select from the dropdown below to see all of the default colors Ionic provides and their variations. | ||
| Each color consists of the following properties: a `base`, `contrast`, `shade`, and `tint`. The `base` and `contrast` colors also require a `rgb` property which is the same color, just in <a href="https://developer.mozilla.org/en-US/docs/Glossary/RGB" target="_blank">rgb format</a>. Refer to [The Alpha Problem](advanced.md#the-alpha-problem) for an explanation of why the `rgb` property is also needed. Select from the dropdown below for all of the default colors Ionic provides and their variations. |
Member
There was a problem hiding this comment.
Suggested change
| Each color consists of the following properties: a `base`, `contrast`, `shade`, and `tint`. The `base` and `contrast` colors also require a `rgb` property which is the same color, just in <a href="https://developer.mozilla.org/en-US/docs/Glossary/RGB" target="_blank">rgb format</a>. Refer to [The Alpha Problem](advanced.md#the-alpha-problem) for an explanation of why the `rgb` property is also needed. Select from the dropdown below for all of the default colors Ionic provides and their variations. | |
| Each color consists of the following properties: a `base`, `contrast`, `shade`, and `tint`. The `base` and `contrast` colors also require a `rgb` property which is the same color, just in <a href="https://developer.mozilla.org/en-US/docs/Glossary/RGB" target="_blank">rgb format</a>. Refer to [The Alpha Problem](advanced.md#the-alpha-problem) for an explanation of why the `rgb` property is also needed. Select from the dropdown below to view all of the default colors Ionic provides and their variations. |
Swapping "to see" for "for" leaves the last sentence not quite parsing, since you select one color from the dropdown rather than selecting for all of them.
| As of now, existing apps aren't required to use the AAB format, but you can still enroll them using Play App signing. | ||
|
|
||
| To opt into app signing, you'll need to upload the app signing key used to sign previous releases of the app. Navigate to Setup -> App integrity, then choose one of the two methods seen in the screenshot below. Once the key has been uploaded, you can enroll in Play App Signing. | ||
| To opt into app signing, you'll need to upload the app signing key used to sign previous releases of the app. Navigate to Setup -> App integrity, then choose one of the two available methods. Once the key has been uploaded, you can enroll in Play App Signing. |
Member
There was a problem hiding this comment.
The screenshot is still directly below this, but the prose no longer points at it and doesn't say what the two methods are, so someone who can't see the image comes away with less than they had before. Naming them would do more for the goal here than dropping the pointer. The similar rewrite earlier on the page is fine as-is, since that sentence still ends in a colon introducing its image.
| ## Fixed Grid | ||
|
|
||
| Grids take up 100% width of their container. By adding the `fixed` property to the grid, the width will be set based on the screen size. The width of the grid for each breakpoint is listed in the table below, but it can be customized. For more information, see [Customizing the Grid](#customizing-the-grid). Open the below example in StackBlitz and resize the screen to see the grid width change. | ||
| Grids take up 100% width of their container. By adding the `fixed` property to the grid, the width will be set based on the screen size. The width of the grid for each breakpoint is listed in the table below, but it can be customized. For more information, refer to [Customizing the Grid](#customizing-the-grid). Open the below example in StackBlitz and resize the screen; the grid width changes. |
Member
There was a problem hiding this comment.
Suggested change
| Grids take up 100% width of their container. By adding the `fixed` property to the grid, the width will be set based on the screen size. The width of the grid for each breakpoint is listed in the table below, but it can be customized. For more information, refer to [Customizing the Grid](#customizing-the-grid). Open the below example in StackBlitz and resize the screen; the grid width changes. | |
| Grids take up 100% width of their container. By adding the `fixed` property to the grid, the width will be set based on the screen size. The width of the grid for each breakpoint is listed in the table below, but it can be customized. For more information, refer to [Customizing the Grid](#customizing-the-grid). Open the below example in StackBlitz and resize the screen to watch the grid width change. |
The semicolon loses the "do this to see that" instruction. You've done it the same way at four other spots on this page so it's consistent either way, this is just a preference from me. Up to you!
Co-Authored-By: Shane <561207+ShaneK@users.noreply.github.com>
thetaPC
force-pushed
the
prettier-ignore
branch
from
August 12, 2026 22:12
9022f9d to
dbdd763
Compare
Co-authored-by: Shane <shane@shanessite.net>
Co-authored-by: Shane <shane@shanessite.net>
Co-authored-by: Shane <shane@shanessite.net>
Co-Authored-By: Shane <561207+ShaneK@users.noreply.github.com>
…to prettier-ignore
Co-authored-by: Shane <shane@shanessite.net>
Co-authored-by: Shane <shane@shanessite.net>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue URL: N/A
What is the current behavior?
Cross-references throughout the docs are written as "see", and many links use non-descriptive text such as "here", "see here", or the raw URL itself. Link text like this gives no indication of the destination when read on its own, which is how screen reader users often navigate a page.
Separately, some prose assumes the reader is reviewing the app visually, with phrasing like "you should see the app appear" or "as seen below".
A few links were also written as bare URLs sitting in prose rather than as proper markdown links.
What is the new behavior?
Cross-references now use "refer to". Link text describes what it points to, so it makes sense read out of context. Bare URLs in prose are now descriptive links. Phrasing that assumed sight has been reworded to describe what happens rather than what the reader looks at, for example "the app now appears" instead of "you should now see the app appear".
Also adds a comment above the existing
prettier-ignoreinindex.mdexplaining why it cannot be removed. Prettier's mdx parser splits the raw anchors in that list across lines, which fails MDX compilation, and the anchors needtarget="_blank"so they cannot become markdown links.Does this introduce a breaking change?
Other information
Some of the diff in
docs/utilities/animations.mdanddocs/utilities/gestures.mdis prettier re-padding markdown tables. Three table cells changed from "See" to "Refer to", which widened a column, so prettier re-flowed the surrounding rows. Those rows have no content change.Scope is the current docs only. Versioned docs (since v7 should be archived soon), the generated
docs/nativeanddocs/cli/commandsdirectories, and the twodocs/testfixture pages are untouched.